diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml new file mode 100644 index 00000000..4052c596 --- /dev/null +++ b/.github/workflows/build.yaml @@ -0,0 +1,173 @@ +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 + if: contains(inputs.tgt, 'Linux') || inputs.tgt == '' + runs-on: ${{ matrix.os }} + strategy: + matrix: + include: + - os: ubuntu-24.04 + platform: amd64 + container: quay.io/pypa/manylinux_2_28_x86_64 + - os: ubuntu-24.04-arm + platform: arm64 + container: quay.io/pypa/manylinux_2_28_aarch64 + + steps: + + - uses: actions/checkout@v4 + with: + submodules: true + + - name: Generate script + run: | + echo export PYO_COMPILE_ARGS=-g0 > build.sh + echo /opt/python/cp39-cp39/bin/python3.9 -m build >> build.sh + echo /opt/python/cp310-cp310/bin/python3.10 -m build >> build.sh + echo /opt/python/cp311-cp311/bin/python3.11 -m build >> build.sh + echo /opt/python/cp312-cp312/bin/python3.12 -m build >> build.sh + echo /opt/python/cp313-cp313/bin/python3.13 -m build >> build.sh + echo cd dist >> build.sh + echo auditwheel repair *.whl >> build.sh + echo rm *.whl >> build.sh + echo mv wheelhouse/*.whl . >> build.sh + chmod +x build.sh + + - name: Build wheels + run: | + docker run \ + -v $(pwd):/io \ + -w /io \ + --platform linux/${{ matrix.platform }} \ + ${{ matrix.container }} \ + ./build.sh + + - name: Upload the artifact + uses: actions/upload-artifact@v4 + with: + name: Linux_${{ matrix.platform }}_wheels + path: dist/*.whl + + build_macos_wheels: + name: Build wheels for ${{ matrix.os }} Python-${{ matrix.python-version}}-${{ matrix.arch }} + if: contains(inputs.tgt, 'macOS') || inputs.tgt == '' + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [macos-latest] + python-version: ['3.9', '3.10', '3.11', '3.12', '3.13'] + arch: ['x86', ''] + exclude: + - os: macos-latest + 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 + + 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.5'] + 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 + if: ${{ always() }} + needs: [build_source_package, build_linux_wheels, build_macos_wheels, build_windows_wheels] + runs-on: ubuntu-latest + + steps: + - uses: actions/upload-artifact/merge@v4 + with: + name: python-oracledb-wheels + delete-merged: true diff --git a/.gitignore b/.gitignore index 4bd0e994..8c791a41 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +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 new file mode 100644 index 00000000..8d193308 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,17 @@ +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files +- repo: https://github.com/psf/black-pre-commit-mirror + rev: 24.4.2 + hooks: + - id: black +- repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.0.291 + hooks: + - id: ruff + exclude: ^samples/tutorial/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b8121add..ad3c3dc1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,51 +1,58 @@ -# Contributing +# Contributing to this repository We welcome your contributions! There are multiple ways to contribute. -## Issues +## Opening issues For bugs or enhancement requests, please file a GitHub issue unless it's -security related. When filing a bug remember that the better written the bug -is, the more likely it is to be fixed. If you think you've found a security -vulnerability, do not raise a GitHub issue and follow the instructions on our -[Security Policy](./.github/SECURITY.md). +security related. When filing a bug remember that the better written the bug is, +the more likely it is to be fixed. If you think you've found a security +vulnerability, do not raise a GitHub issue and follow the instructions in our +[security policy](./SECURITY.md). -## Contributing Code +## Contributing code -To get started, you will need to sign the [Oracle Contributor -Agreement](https://oca.opensource.oracle.com) (OCA). - -For pull requests to be accepted, the bottom of your commit message must have -the following line using the name and e-mail address you used for the OCA. +We welcome your code contributions. Before submitting code via a pull request, +you will need to have signed the [Oracle Contributor Agreement][OCA] (OCA) and +your commits need to include the following line using the name and e-mail +address you used to sign the OCA: ```text Signed-off-by: Your Name ``` -This can be automatically added to pull requests by committing with: +This can be automatically added to pull requests by committing with +`--sign-off` or `-s`, e.g. ```text git commit --signoff ``` -Only pull requests from committers that can be verified as having -signed the OCA can be accepted. +Only pull requests from committers that can be verified as having signed the +OCA can be accepted. -### Pull request process +## Pull request process -1. Fork this repository +1. Ensure there is an issue created to track and discuss the fix or enhancement + you intend to submit. +1. Fork this repository. 1. Create a branch in your fork to implement the changes. We recommend using -the issue number as part of your branch name, e.g. `1234-fixes` + the issue number as part of your branch name, e.g. `1234-fixes`. 1. Ensure that any documentation is updated with the changes that are required -by your fix. + by your change. 1. Ensure that any samples are updated if the base image has been changed. 1. Submit the pull request. *Do not leave the pull request blank*. Explain exactly -what your changes are meant to do and provide simple steps on how to validate -your changes. Ensure that you reference the issue you created as well. -1. We will review your PR before it is merged. + what your changes are meant to do and provide simple steps on how to validate. + your changes. Ensure that you reference the issue you created as well. +1. We will assign the pull request to 2-3 people for review before it is merged. + +Note we merge to an internal repo first before pushing back to GitHub. -## Code of Conduct +## Code of conduct Follow the [Golden Rule](https://en.wikipedia.org/wiki/Golden_Rule). If you'd -like more specific guidelines see the [Contributor Covenant Code of -Conduct](https://www.contributor-covenant.org/version/1/4/code-of-conduct/) +like more specific guidelines, see the [Contributor Covenant Code of +Conduct][COC]. + +[OCA]: https://oca.opensource.oracle.com +[COC]: https://www.contributor-covenant.org/version/1/4/code-of-conduct/ diff --git a/LICENSE.txt b/LICENSE.txt index c36cfc7e..38fd1483 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,4 +1,4 @@ -Copyright (c) 2016, 2022 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/NOTICE.txt b/NOTICE.txt index 5056d047..bc88e116 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -1 +1 @@ -Copyright (c) 2016, 2022, Oracle and/or its affiliates. +Copyright (c) 2016, 2024, Oracle and/or its affiliates. diff --git a/README.md b/README.md index 335ac3ce..f867079f 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,66 @@ -# python-oracledb 1.2 (Development) +# python-oracledb -python-oracledb is a [Python programming language][python] extension module -allowing Python programs to connect to [Oracle Database][oracledb]. It is the -renamed, new major release of the 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. -## Installation +Synchronous and [concurrent][concurrent] coding styles are supported. Database +operations can optionally be [pipelined][pipelining]. -Run `python -m pip install oracledb` +Python-oracledb is the successor to the now obsolete cx_Oracle driver. -See [python-oracledb Installation][installation]. +## Python-oracledb 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.6 through 3.10. +- Python versions 3.9 through 3.13. - Prebuilt packages are available on Windows for Python 3.7 or later, on macOS - for Python 3.7 or later, and on Linux for Python 3.6 or later. + 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 @@ -32,13 +70,13 @@ 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 **Thin mode**: Oracle Database 12.1 (or later) is required. - **Thick mode**: Oracle Database 11.2 (or later) is required, depending on the + **Thick mode**: Oracle Database 9.2 (or later) is required, depending on the Oracle Client library version. Oracle Database's standard client-server version interoperability allows connection to both older and newer databases. For example when python-oracledb uses Oracle Client 19c libraries, @@ -49,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]. @@ -66,11 +99,18 @@ See [/tests][tests] ## Contributing -See [CONTRIBUTING](https://github.com/oracle/python-oracledb/blob/main/CONTRIBUTING.md) +This project welcomes contributions from the community. Before submitting a +pull request, please [review our contribution guide](./CONTRIBUTING.md). + +## Security + +Please consult the [security guide](./SECURITY.md) for our responsible security +vulnerability disclosure process. ## License -See [LICENSE][license], [THIRD_PARTY_LICENSES][tplicense], and [NOTICE][notice]. +See [LICENSE][license], [THIRD_PARTY_LICENSES][tplicense], and +[NOTICE][notice]. [python]: https://www.python.org/ [oracledb]: https://www.oracle.com/database/ @@ -88,3 +128,6 @@ See [LICENSE][license], [THIRD_PARTY_LICENSES][tplicense], and [NOTICE][notice]. [samples]: https://github.com/oracle/python-oracledb/tree/main/samples [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/README.txt b/README.txt index 7df683ff..2d8b906f 100644 --- a/README.txt +++ b/README.txt @@ -2,4 +2,3 @@ Please see the python-oracledb home page for links to documentation, installation instructions, and source code: https://oracle.github.io/python-oracledb/index.html - diff --git a/.github/SECURITY.md b/SECURITY.md similarity index 68% rename from .github/SECURITY.md rename to SECURITY.md index fb238413..25e76bf5 100644 --- a/.github/SECURITY.md +++ b/SECURITY.md @@ -7,9 +7,9 @@ and privacy of all our users. Please do NOT raise a GitHub Issue to report a security vulnerability. If you believe you have found a security vulnerability, please submit a report to [secalert_us@oracle.com][1] preferably with a proof of concept. Please review -some additional information on [how to report security vulnerabilities to Oracle][2]. -We encourage people who contact Oracle Security to use email encryption using -[our encryption key][3]. +some additional information on [how to report security vulnerabilities to +Oracle][2]. We encourage people who contact Oracle Security to use email +encryption using [our encryption key][3]. We ask that you do not use other channels or contact the project maintainers directly. @@ -20,17 +20,16 @@ security features are welcome on GitHub Issues. ## Security updates, alerts and bulletins Security updates will be released on a regular cadence. Many of our projects -will typically release security fixes in conjunction with the -[Oracle Critical Patch Update][3] program. Additional -information, including past advisories, is available on our [security alerts][4] -page. +will typically release security fixes in conjunction with the Oracle Critical +Patch Update program. Additional information, including past advisories, is +available on our [security alerts][4] page. ## Security-related information -We will provide security related information such as a threat model, considerations -for secure use, or any known security issues in our documentation. Please note -that labs and sample code are intended to demonstrate a concept and may not be -sufficiently hardened for production use. +We will provide security related information such as a threat model, +considerations for secure use, or any known security issues in our +documentation. Please note that labs and sample code are intended to +demonstrate a concept and may not be sufficiently hardened for production use. [1]: mailto:secalert_us@oracle.com [2]: https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html diff --git a/THIRD_PARTY_LICENSES.txt b/THIRD_PARTY_LICENSES.txt index b9b375f8..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 @@ -454,3 +462,11994 @@ 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/Makefile b/doc/Makefile index dcce650f..cac132a1 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,4 +1,4 @@ -# Makefile to generate cx_Oracle documentation using Sphinx +# Makefile to generate python-oracledb documentation using Sphinx SPHINXOPTS = SPHINXBUILD = sphinx-build @@ -20,4 +20,3 @@ pdf: .PHONY: clean clean: rm -rf $(BUILDDIR)/* - diff --git a/doc/requirements.txt b/doc/requirements.txt index 33cdde47..dcc8e5c8 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,2 +1,2 @@ sphinx>=4.2.0 -sphinx-rtd-theme +sphinx-rtd-theme>=0.5.2 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/_ext/oracle_deprecated.py b/doc/src/_ext/oracle_deprecated.py index 589e1877..f02b60e4 100644 --- a/doc/src/_ext/oracle_deprecated.py +++ b/doc/src/_ext/oracle_deprecated.py @@ -1,5 +1,5 @@ -#------------------------------------------------------------------------------ -# Copyright (c) 2022, Oracle and/or its affiliates. +# ----------------------------------------------------------------------------- +# Copyright (c) 2022, 2023, 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 @@ -20,20 +20,21 @@ # 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. -#------------------------------------------------------------------------------ +# ----------------------------------------------------------------------------- -#------------------------------------------------------------------------------ +# ----------------------------------------------------------------------------- # oracle_deprecated.py # -# Overrides the 'deprecated' directive so that it can a componment name can be -# used in conjunction with the version. -#------------------------------------------------------------------------------ +# Overrides the 'deprecated' directive so that a componment name can be used in +# conjunction with the version. +# ----------------------------------------------------------------------------- from docutils import nodes from docutils.parsers.rst import Directive from sphinx import addnodes + class DriverDeprecated(Directive): has_content = True required_arguments = 1 @@ -43,22 +44,22 @@ class DriverDeprecated(Directive): def run(self): node = addnodes.versionmodified() node.document = self.state.document - node['type'] = self.name - node['version'] = self.arguments[0] - text = 'Deprecated since {}.'.format(self.arguments[0]) - classes = ['versionmodified', 'deprecated'] - para = nodes.paragraph('', '', - nodes.inline('', text, classes=classes), - translatable=False) + node["type"] = self.name + node["version"] = self.arguments[0] + text = "Deprecated since {}.".format(self.arguments[0]) + classes = ["versionmodified", "deprecated"] + para = nodes.paragraph( + "", "", nodes.inline("", text, classes=classes), translatable=False + ) node.append(para) - ret: List[Node] = [node] - return ret + return [node] + def setup(app): app.add_directive("deprecated", DriverDeprecated, override=True) return { - 'version': '0.1', - 'parallel_read_safe': True, - 'parallel_write_safe': True, + "version": "0.1", + "parallel_read_safe": True, + "parallel_write_safe": True, } diff --git a/doc/src/_ext/table_with_summary.py b/doc/src/_ext/table_with_summary.py index bb357632..96ecdd00 100644 --- a/doc/src/_ext/table_with_summary.py +++ b/doc/src/_ext/table_with_summary.py @@ -1,5 +1,5 @@ -#------------------------------------------------------------------------------ -# Copyright (c) 2022, Oracle and/or its affiliates. +# ----------------------------------------------------------------------------- +# Copyright (c) 2022, 2024, 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 @@ -20,14 +20,14 @@ # 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. -#------------------------------------------------------------------------------ +# ----------------------------------------------------------------------------- -#------------------------------------------------------------------------------ +# ----------------------------------------------------------------------------- # table_with_summary.py # # Defines a directive (list-table-with-summary) that adds support for a summary # option on top of the regular "list-table" directive. -#------------------------------------------------------------------------------ +# ----------------------------------------------------------------------------- import sphinx from docutils.parsers.rst import directives @@ -35,14 +35,14 @@ from packaging import version -class ListTableWithSummary(tables.ListTable): - option_spec = {'summary': directives.unchanged} +class ListTableWithSummary(tables.ListTable): + option_spec = {"summary": directives.unchanged} option_spec.update(tables.ListTable.option_spec) def run(self): result = super().run() - summary = self.options.get('summary') + summary = self.options.get("summary") if summary: table_node = result[0] table_node["summary"] = summary @@ -50,29 +50,45 @@ def run(self): class HTMLTranslator(sphinx.writers.html5.HTML5Translator): + def visit_paragraph(self, node): + children = node.children + if len(children) == 1 and children[0].astext() == "No relevant notes": + atts = { + "style": "clip: rect(1px, 1px, 1px, 1px);" + "clip-path: inset(50%);" + "height: 1px;" + "overflow: hidden;" + "position: absolute;" + "white-space: nowrap;" + "width: 1px;" + } + self.body.append(self.starttag(node, "p", "", **atts)) + else: + super().visit_paragraph(node) def visit_table(self, node): - if version.parse(sphinx.__version__) > version.parse('4.2.0'): + if version.parse(sphinx.__version__) > version.parse("4.2.0"): self._table_row_indices = [0] else: self._table_row_index = 0 atts = {} - classes = [cls.strip(' \t\n') \ - for cls in self.settings.table_style.split(',')] + classes = [ + cls.strip(" \t\n") for cls in self.settings.table_style.split(",") + ] classes.insert(0, "docutils") # compat # set align-default if align not specified to give a default style - classes.append('align-%s' % node.get('align', 'default')) + classes.append("align-%s" % node.get("align", "default")) - if 'width' in node: - atts['style'] = 'width: %s' % node['width'] - if 'summary' in node: - atts['summary'] = node['summary'] - tag = self.starttag(node, 'table', CLASS=' '.join(classes), **atts) + if "width" in node: + atts["style"] = "width: %s" % node["width"] + if "summary" in node: + atts["summary"] = node["summary"] + tag = self.starttag(node, "table", CLASS=" ".join(classes), **atts) self.body.append(tag) def setup(app): - app.add_directive('list-table-with-summary', ListTableWithSummary) + app.add_directive("list-table-with-summary", ListTableWithSummary) app.set_translator("html", HTMLTranslator, override=True) diff --git a/doc/src/api_manual/aq.rst b/doc/src/api_manual/aq.rst index c54a9306..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 @@ -43,26 +41,26 @@ Queue Methods .. method:: Queue.enqmany(messages) - Enqueues multiple messages into the queue. The ``messages`` parameter must be a - sequence containing :ref:`message property ` objects which - have all had their payload attribute set to a value that the queue + Enqueues multiple messages into the queue. The ``messages`` parameter must + be a sequence containing :ref:`message property ` objects + which have all had their payload attribute set to a value that the queue supports. .. warning:: - Calling this function 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. - + 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 to work for a period of time. - .. method:: Queue.enqone(message) Enqueues a single message into the queue. The message must be a @@ -87,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 @@ -96,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 @@ -107,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. @@ -119,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 @@ -214,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 @@ -249,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 @@ -313,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 @@ -322,15 +315,14 @@ Message Properties payload that was dequeued when using a :ref:`queue `. When enqueuing, the value is checked to ensure that it conforms to the type expected by that queue. For RAW queues, the value can be a bytes object or a string. If the - value is a string it will first be converted to bytes by encoding in the - encoding identified by the attribute :attr:`Connection.encoding`. + value is a string it will first be converted to bytes in the encoding UTF-8. .. attribute:: MessageProperties.priority 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 @@ -340,7 +332,7 @@ Message Properties :data:`~oracledb.MSG_READY`, :data:`~oracledb.MSG_PROCESSED` or :data:`~oracledb.MSG_EXPIRED`. -.. attribute:: Messageproperties.recipient +.. attribute:: MessageProperties.recipients This read-write attribute specifies a list of recipient names that can be associated with a message at the time of enqueuing the message. This allows a 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 new file mode 100644 index 00000000..1bf156dc --- /dev/null +++ b/doc/src/api_manual/async_connection.rst @@ -0,0 +1,717 @@ +.. _asyncconnobj: + +**************************** +API: AsyncConnection Objects +**************************** + +An AsyncConnection object can be created with :meth:`oracledb.connect_async()` +or with :meth:`AsyncConnectionPool.acquire()`. AsyncConnections support use of +concurrent programming with `asyncio `__. Unless explicitly noted as synchronous, the AsyncConnection +methods should be used with ``await``. + +.. dbapiobjectextension:: + +.. versionadded:: 2.0.0 + +.. note:: + + AsyncConnection objects are only supported in the python-oracledb Thin + mode. + +.. note:: + + Any outstanding database transaction will be rolled back when the + connection object is destroyed or closed. You must perform a + :meth:`commit ` first if you want data to + persist in the database, see :ref:`txnasync`. + +.. _asyncconnmeth: + +AsyncConnection Methods +======================= + +.. method:: AsyncConnection.__aenter__() + + The entry point for the asynchronous connection as a context manager. It + returns itself. + +.. method:: AsyncConnection.__aexit__() + + The exit point for the asynchronous connection as a context manager. This + will close the connection and roll back any uncommitted transaction. + +.. method:: AsyncConnection.callfunc(name, return_type, parameters=None, \ + keyword_parameters=None) + + Calls a PL/SQL function with the given name. + + This is a shortcut for calling :meth:`AsyncConnection.cursor()`, + :meth:`AsyncCursor.callfunc()`, and then :meth:`AsyncCursor.close()`. + +.. method:: AsyncConnection.callproc(name, parameters=None, \ + keyword_parameters=None) + + Calls a PL/SQL procedure with the given name. + + This is a shortcut for calling :meth:`AsyncConnection.cursor()`, + :meth:`AsyncCursor.callproc()`, and then :meth:`AsyncCursor.close()`. + +.. method:: AsyncConnection.cancel() + + A synchronous method that breaks a long-running statement. + +.. method:: AsyncConnection.changepassword(old_password, new_password) + + Changes the password for the user to which the connection is connected. + +.. method:: AsyncConnection.close() + + Closes the connection. + +.. method:: AsyncConnection.commit() + + Commits any pending transaction to the database. + +.. method:: AsyncConnection.createlob(lob_type) + + Creates and returns a new temporary LOB of the specified type. + +.. method:: AsyncConnection.cursor(scrollable=False) + + A synchronous method that returns an :ref:`AsyncCursor object + ` associated with the connection. + +.. method:: AsyncConnection.decode_oson(data) + + A synchronous method that decodes `OSON-encoded + `__ + bytes and returns the object encoded in those bytes. This is useful for + fetching columns which have the check constraint ``IS JSON FORMAT OSON`` + enabled. + + .. versionadded:: 2.1.0 + +.. method:: AsyncConnection.encode_oson(value) + + A synchronous method that encodes a Python value into `OSON-encoded + `__ + bytes and returns them. This is useful for inserting into columns which + have the check constraint ``IS JSON FORMAT OSON`` enabled. + + .. versionadded:: 2.1.0 + +.. method:: AsyncConnection.execute(statement, parameters=None) + + Executes a statement against the database. + + This is a shortcut for calling :meth:`AsyncConnection.cursor()`, + :meth:`AsyncCursor.execute()`, and then :meth:`AsyncCursor.close()` + +.. method:: AsyncConnection.executemany(statement, parameters) + + Executes a SQL statement once using all bind value mappings or sequences + found in the sequence parameters. This can be used to insert, update, or + delete multiple rows in a table with a single python-oracledb call. It can + also invoke a PL/SQL procedure multiple times. + + The ``parameters`` parameter can be a list of tuples, where each tuple item + maps to one bind variable placeholder in ``statement``. It can also be a + list of dictionaries, where the keys match the bind variable placeholder + names in ``statement``. If there are no bind values, or values have + previously been bound, the ``parameters`` value can be an integer + specifying the number of iterations. + + 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) + + Executes a query and returns all of the rows. + + The default value for ``arraysize`` is :attr:`defaults.arraysize`. + + Internally, this method's :attr:`Cursor.prefetchrows` size is set to the + value of the explicit or default ``arraysize`` parameter value. + + This is a shortcut for calling :meth:`AsyncConnection.cursor()`, + :meth:`AsyncCursor.fetchall()`, and then :meth:`AsyncCursor.close()`. + +.. method:: AsyncConnection.fetchmany(statement, parameters=None, \ + num_rows=None, rowfactory=None) + + Executes a query and returns up to the specified number of rows. + + The default value for ``num_rows`` is the value of + :attr:`defaults.arraysize`. + + Internally, this method's :attr:`Cursor.prefetchrows` size is set to the + value of the explicit or default ``num_rows`` parameter, allowing all rows + to be fetched in one :ref:`round-trip ` + + Since only one fetch is performed for a query, consider adding a ``FETCH + NEXT`` clause to the statement to prevent the database processing rows that + will never be fetched, see :ref:`rowlimit`. + + This a shortcut for calling :meth:`AsyncConnection.cursor()`, + :meth:`AsyncCursor.fetchmany()`, and then :meth:`AsyncCursor.close()`. + +.. method:: AsyncConnection.fetchone(statement, parameters=None, \ + rowfactory=None) + + Executes a query and returns the first row of the result set if one exists + (or *None* if no rows exist). + + Internally, this method's :attr:`Cursor.prefetchrows` and + :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 + database processing rows that will never be fetched, see :ref:`rowlimit`. + + This a shortcut for calling :meth:`AsyncConnection.cursor()`, + :meth:`AsyncCursor.fetchone()`, and then :meth:`AsyncCursor.close()`. + +.. method:: AsyncConnection.gettype(name) + + Returns a :ref:`type object ` given its name. This can then + be used to create objects which can be bound to cursors created by this + connection. + +.. method:: AsyncConnection.is_healthy() + + A synchronous method that returns a boolean indicating the health status + of a connection. + + Connections may become unusable in several cases, such as, if the network + socket is broken, if an Oracle error indicates the connection is unusable, + or after receiving a planned down notification from the database. + + This function is best used before starting a new database request on an + existing standalone connection. Pooled connections internally perform this + check before returning a connection to the application. + + If this function returns *False*, the connection should be not be used by + the application and a new connection should be established instead. + + This function performs a local check. To fully check a connection's health, + use :meth:`AsyncConnection.ping()` which performs a :ref:`round-trip + ` to the database. + +.. method:: AsyncConnection.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. + +.. method:: AsyncConnection.run_pipeline(pipeline, continue_on_error=False) + + Runs all of the operations in the :ref:`pipeline ` and returns + a list of :ref:`PipelineOpResult Objects `, each + entry corresponding to an operation executed in the pipeline. + + The ``continue_on_error`` parameter determines whether operations should + continue to run after an error has occurred. If this parameter is set to + *True*, then the :attr:`PipelineOpResult.error` attribute will be populated + with an :ref:`_Error ` instance which identifies the error + that occurred. If this parameter is set to *False*, then an exception will + be raised as soon as an error is detected and all subsequent operations + will be terminated. The default value is *False*. + + See :ref:`pipelining` for more information. + + .. note:: + + True pipelining requires Oracle Database 23ai. + + When you connect to an older database, operations are sequentially + executed by python-oracledb. Each operation concludes before the next + is sent to the database. There is no reduction in round-trips and no + performance benefit. This usage is only recommended for code + portability such as when preparing for a database upgrade. + + .. versionadded:: 2.4.0 + +.. method:: AsyncConnection.tpc_begin(xid, flags, timeout) + + Begins a Two-Phase Commit (TPC) on a global transaction using the specified + transaction identifier (xid). + + The ``xid`` parameter should be an object returned by the + :meth:`~Connection.xid()` method. + + The ``flags`` parameter is one of the constants + :data:`oracledb.TPC_BEGIN_JOIN`, :data:`oracledb.TPC_BEGIN_NEW`, + :data:`oracledb.TPC_BEGIN_PROMOTE`, or :data:`oracledb.TPC_BEGIN_RESUME`. + The default is :data:`oracledb.TPC_BEGIN_NEW`. + + The ``timeout`` parameter is the number of seconds to wait for a + transaction to become available for resumption when + :data:`~oracledb.TPC_BEGIN_RESUME` is specified in the ``flags`` parameter. + When :data:`~oracledb.TPC_BEGIN_NEW` is specified in the ``flags`` + parameter, the ``timeout`` parameter indicates the number of seconds the + transaction can be inactive before it is automatically terminated by the + system. A transaction is inactive between the time it is detached with + :meth:`AsyncConnection.tpc_end()` and the time it is resumed with + :meth:`AsyncConnection.tpc_begin()`.The default is *0* seconds. + + The following code sample demonstrates the ``tpc_begin()`` function:: + + x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + await connection.tpc_begin(xid=x, flags=oracledb.TPC_BEGIN_NEW, timeout=30) + + See :ref:`tpc` for information on TPC. + + .. versionadded:: 2.3.0 + +.. method:: AsyncConnection.tpc_commit(xid, one_phase) + + Commits a global transaction. When called with no arguments, this method + commits a transaction previously prepared with + :meth:`~AsyncConnection.tpc_begin()` and optionally prepared with + :meth:`~AsyncConnection.tpc_prepare()`. If + :meth:`~AsyncConnection.tpc_prepare()` is not called, a single phase commit + is performed. A transaction manager may choose to do this if only a single + resource is participating in the global transaction. + + If an ``xid`` parameter is passed, then an object should be returned by the + :meth:`~Connection.xid()` function. This form should be called outside of a + transaction and is intended for use in recovery. + + The ``one_phase`` parameter is a boolean identifying whether to perform a + one-phase or two-phase commit. If ``one_phase`` parameter is *True*, a + single-phase commit is performed. The default value is *False*. This + parameter is only examined if a value is provided for the ``xid`` + parameter. Otherwise, the driver already knows whether + :meth:`~AsyncConnection.tpc_prepare()` was called for the transaction and + whether a one-phase or two-phase commit is required. + + The following code sample demonstrates the ``tpc_commit()`` function:: + + x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + await connection.tpc_commit(xid=x, one_phase=False) + + See :ref:`tpc` for information on TPC. + + .. versionadded:: 2.3.0 + +.. method:: AsyncConnection.tpc_end(xid, flags) + + Ends or suspends work on a global transaction. This function is only + intended for use by transaction managers. + + If an ``xid`` parameter is passed, then an object should be returned by the + :meth:`~Connection.xid()` function. If no xid parameter is passed, then the + transaction identifier used by the previous :meth:`~Connection.tpc_begin()` + is used. + + The ``flags`` parameter is one of the constants + :data:`oracledb.TPC_END_NORMAL` or :data:`oracledb.TPC_END_SUSPEND`. The + default is :data:`oracledb.TPC_END_NORMAL`. + + If the flag is :data:`oracledb.TPC_END_SUSPEND` then the transaction may be + resumed later by calling :meth:`AsyncConnection.tpc_begin()` with the flag + :data:`oracledb.TPC_BEGIN_RESUME`. + + The following code sample demonstrates the ``tpc_end()`` function:: + + x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + await connection.tpc_end(xid=x, flags=oracledb.TPC_END_NORMAL) + + See :ref:`tpc` for information on TPC. + + .. versionadded:: 2.3.0 + +.. method:: AsyncConnection.tpc_forget(xid) + + Causes the database to forget a heuristically completed TPC transaction. + This function is only intended to be called by transaction managers. + + The ``xid`` parameter is mandatory and should be an object should be + returned by the :meth:`~Connection.xid()` function. + + The following code sample demonstrates the ``tpc_forget()`` function:: + + x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + await connection.tpc_forget(xid=x) + + See :ref:`tpc` for information on TPC. + + .. versionadded:: 2.3.0 + +.. method:: AsyncConnection.tpc_prepare(xid) + + Prepares a two-phase transaction for commit. After this function is called, + no further activity should take place on this connection until either + :meth:`~AsyncConnection.tpc_commit()` or + :meth:`~AsyncConnection.tpc_rollback()` have been called. + + Returns a boolean indicating whether a commit is needed or not. If you + attempt to commit when not needed, then it results in the error + ``ORA-24756: transaction does not exist``. + + If an ``xid`` parameter is passed, then an object should be returned by the + :meth:`~Connection.xid()` function. If an ``xid`` parameter is not passed, + then the transaction identifier used by the previous + :meth:`~AsyncConnection.tpc_begin()` is used. + + The following code sample demonstrates the ``tpc_prepare()`` function:: + + x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + await connection.tpc_prepare(xid=x) + + See :ref:`tpc` for information on TPC. + + .. versionadded:: 2.3.0 + +.. method:: AsyncConnection.tpc_recover() + + Returns a list of pending transaction identifiers that require recovery. + Objects of type ``Xid`` (as returned by the :meth:`~Connection.xid()` + function) are returned and these can be passed to + :meth:`~AsyncConnection.tpc_commit()` or + :meth:`~AsyncConnection.tpc_rollback()` as needed. + + This function queries the view ``DBA_PENDING_TRANSACTIONS`` and requires + ``SELECT`` privilege on that view. + + The following code sample demonstrates the ``tpc_recover()`` function:: + + await connection.tpc_recover() + + See :ref:`tpc` for information on TPC. + + .. versionadded:: 2.3.0 + +.. method:: AsyncConnection.tpc_rollback(xid) + + Rolls back a global transaction. + + If an ``xid`` parameter is not passed, then it rolls back the transaction + that was previously started with :meth:`~AsyncConnection.tpc_begin()`. + + If an ``xid`` parameter is passed, then an object should be returned by + :meth:`~Connection.xid()` and the specified transaction is rolled back. + This form should be called outside of a transaction and is intended for use + in recovery. + + The following code sample demonstrates the ``tpc_rollback()`` function:: + + x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + await connection.tpc_rollback(xid=x) + + See :ref:`tpc` for information on TPC. + + .. versionadded:: 2.3.0 + +.. _asynconnattr: + +AsyncConnection Attributes +========================== + +.. attribute:: AsyncConnection.action + + This write-only attribute sets the ACTION column in the V$SESSION view. It + is a string attribute but the value *None* is accepted and treated as an + empty string. + +.. attribute:: AsyncConnection.autocommit + + This read-write attribute determines whether autocommit mode is on or off. + When autocommit mode is on, all statements are committed as soon as they + have completed executing. + +.. attribute:: AsyncConnection.call_timeout + + This read-write attribute specifies the amount of time (in milliseconds) + that a single round-trip to the database may take before a timeout will + occur. A value of *0* means that no timeout will take place. + + If a timeout occurs, the error ``DPI-1067`` will be returned if the + connection is still usable. Alternatively, the error ``DPI-1080`` will be + returned if the connection has become invalid and can no longer be used. + +.. attribute:: AsyncConnection.client_identifier + + This write-only attribute sets the CLIENT_IDENTIFIER column in the + V$SESSION view. + +.. attribute:: AsyncConnection.clientinfo + + This write-only attribute sets the CLIENT_INFO column in the V$SESSION + view. + +.. attribute:: AsyncConnection.current_schema + + This read-write attribute sets the current schema attribute for the + session. Setting this value is the same as executing the SQL statement + ``ALTER SESSION SET CURRENT_SCHEMA``. The attribute is set (and verified) on + the next call that does a round trip to the server. The value is placed + before unqualified database objects in SQL statements you then execute. + +.. attribute:: AsyncConnection.db_domain + + This read-only attribute specifies the Oracle Database domain name + associated with the connection. It is the same value returned by the SQL + ``SELECT value FROM V$PARAMETER WHERE NAME = 'db_domain'``. + +.. attribute:: AsyncConnection.db_name + + This read-only attribute specifies the Oracle Database name associated with + the connection. It is the same value returned by the SQL + ``SELECT NAME FROM V$DATABASE``. + +.. attribute:: AsyncConnection.dbop + + This write-only attribute sets the database operation that is to be + monitored. This can be viewed in the DBOP_NAME column of the + V$SQL_MONITOR view. + +.. attribute:: AsyncConnection.dsn + + This read-only attribute returns the TNS entry of the database to which a + connection has been established. + +.. attribute:: AsyncConnection.econtext_id + + This write-only attribute specifies the execution context id. This value + can be found as the ECID column in the V$SESSION view and ECONTEXT_ID in + the auditing tables. The maximum length is 64 bytes. + +.. attribute:: AsyncConnection.edition + + This read-only attribute gets the session edition and is only available + with Oracle Database 11.2, or later. + +.. attribute:: AsyncConnection.external_name + + This read-write attribute specifies the external name that is used by the + connection when logging distributed transactions. + +.. attribute:: AsyncConnection.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. + +.. attribute:: AsyncConnection.instance_name + + This read-only attribute specifies the Oracle Database instance name + associated with the connection. It is the same value as the SQL expression + ``sys_context('userenv', 'instance_name')``. + +.. attribute:: AsyncConnection.internal_name + + This read-write attribute specifies the internal name that is used by the + connection when logging distributed transactions. + +.. attribute:: AsyncConnection.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. + + .. note: + + This attribute is only available with Oracle Database 12.1 or later. + +.. attribute:: AsyncConnection.max_identifier_length + + This read-only attribute specifies the maximum database identifier length + in bytes supported by the database to which the connection has been + established. See `Database Object Naming Rules + `__. + + .. versionadded:: 2.5.0 + +.. attribute:: AsyncConnection.max_open_cursors + + This read-only attribute specifies the maximum number of cursors that the + database can have open concurrently. It is the same value returned by the + SQL ``SELECT VALUE FROM V$PARAMETER WHERE NAME = 'open_cursors'``. + +.. attribute:: AsyncConnection.module + + This write-only attribute sets the MODULE column in the V$SESSION view. + The maximum length for this string is 48 and if you exceed this length you + will get ``ORA-24960``. + +.. 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 + default behavior will take place for all columns fetched from cursors. + + See :ref:`outputtypehandlers`. + +.. attribute:: AsyncConnection.sdu + + This read-only attribute specifies the size of the Session Data Unit (SDU) + that is being used by the connection. The value will be the lesser of the + requested python-oracledb size and the maximum size allowed by the database + network configuration. + +.. attribute:: AsyncConnection.serial_num + + This read-only attribute specifies the session serial number associated with + the connection. It is the same value returned by the SQL + ``SELECT SERIAL# FROM V$SESSION``. + + It is available only in python-oracledb Thin mode. + + 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. + + .. dbapiattributeextension:: + + .. versionadded:: 2.5.0 + +.. attribute:: AsyncConnection.service_name + + This read-only attribute specifies the Oracle Database service name + associated with the connection. This is the same value returned by the SQL + ``SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL``. + +.. attribute:: AsyncConnection.session_id + + This read-only attribute specifies the session identifier associated with + the connection. It is the same value returned by the SQL + ``SELECT SID FROM V$SESSION``. + + It is available only in python-oracledb Thin mode. + + 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. + + .. dbapiattributeextension:: + + .. versionadded:: 2.5.0 + +.. attribute:: AsyncConnection.stmtcachesize + + This read-write attribute specifies the size of the statement cache. This + value can make a significant difference in performance if you have a small + number of statements that you execute repeatedly. + + The default value is *20*. + + See :ref:`Statement Caching ` for more information. + +.. attribute:: AsyncConnection.thin + + This read-only attribute returns a boolean indicating if the connection was + established with the python-oracledb Thin mode (*True*) or python-oracledb + Thick mode (*False*). + +.. attribute:: AsyncConnection.transaction_in_progress + + This read-only attribute specifies whether a transaction is currently in + progress on the database associated with the connection. + +.. attribute:: AsyncConnection.username + + This read-only attribute returns the name of the user which established the + connection to the database. + +.. attribute:: AsyncConnection.version + + This read-only attribute returns the version of the database to which a + connection has been established. diff --git a/doc/src/api_manual/async_connection_pool.rst b/doc/src/api_manual/async_connection_pool.rst new file mode 100644 index 00000000..ad3effad --- /dev/null +++ b/doc/src/api_manual/async_connection_pool.rst @@ -0,0 +1,209 @@ +.. _asyncconnpoolobj: + +******************************** +API: AsyncConnectionPool Objects +******************************** + +An AsyncConnectionPool object can be created with +:meth:`oracledb.create_pool_async()`. + +.. dbapiobjectextension:: + +.. versionadded:: 2.0.0 + +.. note:: + + AsyncConnectionPool objects are only supported in the python-oracledb Thin + mode. + +.. _asynconnpoolmeth: + +AsyncConnectionPool Methods +=========================== + +.. method:: AsyncConnectionPool.acquire(user=None, password=None, cclass=None, \ + purity=oracledb.PURITY_DEFAULT, tag=None, matchanytag=False, \ + shardingkey=[], supershardingkey=[]) + + Acquires a connection from the pool and returns an + :ref:`asynchronous connection object `. + + If the pool is :ref:`homogeneous `, the ``user`` and + ``password`` parameters cannot be specified. If they are, an exception will + be raised. + + The ``cclass`` parameter, if specified, should be a string corresponding to + the connection class for :ref:`drcp`. + + The ``purity`` parameter is expected to be one of + :data:`~oracledb.PURITY_NEW`, :data:`~oracledb.PURITY_SELF`, or + :data:`~oracledb.PURITY_DEFAULT`. + + The ``tag``, ``matchanytag``, ``shardingkey``, and ``supershardingkey`` + parameters are ignored in python-oracledb Thin mode. + +.. method:: AsyncConnectionPool.close(force=False) + + Closes the pool now, rather than when the last reference to it is + released, which makes it unusable for further work. + + If any connections have been acquired and not released back to the pool, + this method will fail unless the ``force`` parameter is set to *True*. + +.. method:: AsyncConnectionPool.drop(connection) + + Drops the connection from the pool which is useful if the connection is no + longer usable (such as when the session is killed). + +.. method:: AsyncConnectionPool.release(connection, tag=None) + + Releases the connection back to the pool now, rather than whenever + ``__del__`` is called. The connection will be unusable from this point + forward; an Error exception will be raised if any operation is attempted + with the connection. Any cursors or LOBs created by the connection will + also be marked unusable and an Error exception will be raised if any + operation is attempted with them. + + Internally, references to the connection are held by cursor objects, + LOB objects, and so on. Once all of these references are released, the + connection itself will be released back to the pool automatically. Either + control references to these related objects carefully or explicitly + release connections back to the pool in order to ensure sufficient + resources are available. + + The ``tag`` parameter is ignored in python-oracledb Thin mode. + +.. _asyncconnpoolattr: + +AsyncConnectionPool Attributes +============================== + +.. attribute:: AsyncConnectionPool.busy + + This read-only attribute returns the number of connections currently + acquired. + +.. attribute:: AsyncConnectionPool.dsn + + This read-only attribute returns the TNS entry of the database to which a + connection has been established. + +.. attribute:: AsyncConnectionPool.getmode + + This read-write attribute determines how connections are returned from the + pool. If :data:`~oracledb.POOL_GETMODE_FORCEGET` is specified, a new + connection will be returned even if there are no free connections in the + pool. :data:`~oracledb.POOL_GETMODE_NOWAIT` will raise an exception if + there are no free connections are available in the pool. If + :data:`~oracledb.POOL_GETMODE_WAIT` is specified and there are no free + connections in the pool, the caller will wait until a free connection is + available. :data:`~oracledb.POOL_GETMODE_TIMEDWAIT` uses the value of + :data:`~ConnectionPool.wait_timeout` to determine how long the caller + should wait for a connection to become available before returning an error. + +.. attribute:: AsyncConnectionPool.homogeneous + + This read-only boolean attribute indicates whether the pool is considered + :ref:`homogeneous ` or not. If the pool is not homogeneous, + different authentication can be used for each connection acquired from the + pool. + +.. attribute:: AsyncConnectionPool.increment + + This read-only attribute returns the number of connections that will be + established when additional connections need to be created. + +.. attribute:: AsyncConnectionPool.max + + This read-only attribute returns the maximum number of connections that the + pool can control. + +.. attribute:: AsyncConnectionPool.max_lifetime_session + + 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 + + This read-write attribute returns the number of sessions that can be + created per shard in the pool. This attribute cannot be used in + python-oracledb Thin mode. + +.. attribute:: AsyncConnectionPool.min + + This read-only attribute returns the number of connections with which the + connection pool was created and the minimum number of connections that will + be controlled by the connection pool. + +.. attribute:: AsyncConnectionPool.name + + This read-only attribute returns the name assigned to the pool by Oracle. + +.. attribute:: AsyncConnectionPool.opened + + This read-only attribute returns the number of connections currently opened + by the pool. + +.. attribute:: AsyncConnectionPool.ping_interval + + This read-write integer attribute specifies the pool ping interval in + seconds. When a connection is acquired from the pool, a check is first made + to see how long it has been since the connection was put into the pool. If + this idle time exceeds ``ping_interval``, then a :ref:`round-trip + ` ping to the database is performed. If the connection is + unusable, it is discarded and a different connection is selected to be + returned by :meth:`AsyncConnectionPool.acquire()`. Setting + ``ping_interval`` to a negative value disables pinging. Setting it to *0* + forces a ping for every :meth:`AsyncConnectionPool.acquire()` and is not + recommended. + +.. attribute:: AsyncConnectionPool.soda_metadata_cache + + This read-write boolean attribute returns whether the SODA metadata cache + is enabled or not. This attribute cannot be used in python-oracledb Thin + mode. + +.. attribute:: AsyncConnectionPool.stmtcachesize + + This read-write attribute specifies the size of the statement cache that + will be used for connections obtained from the pool. Once a connection is + created, that connection’s statement cache size can only be changed by + setting the ``stmtcachesize`` attribute on the connection itself. + + See :ref:`Statement Caching ` for more information. + +.. attribute:: AsyncConnectionPool.thin + + This attribute returns a boolean which indicates the python-oracledb mode + in which the pool was created. If the value of this attribute is *True*, it + indicates that the pool was created in the python-oracledb Thin mode. If + the value of this attribute is *False*, it indicates that the pool was + created in the python-oracledb Thick mode. + +.. attribute:: AsyncConnectionPool.timeout + + This read-only attribute is an integer that specifies the length of time + (in seconds) that a connection may remain idle in the pool before it is + terminated. This applies only when the pool has more than ``min`` + connections open, allowing it to shrink to the specified minimum size. The + default value is *0* seconds. A value of *0* means that there is no maximum + time. + +.. attribute:: AsyncConnectionPool.username + + This read-only attribute returns the name of the user which established the + connection to the database. + +.. attribute:: AsyncConnectionPool.wait_timeout + + This read-write attribute specifies the time (in milliseconds) that the + caller should wait for a connection to become available in the pool before + returning with an error. This value is only used if the ``getmode`` + parameter to :meth:`oracledb.create_pool_async()` was the value + :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. diff --git a/doc/src/api_manual/async_cursor.rst b/doc/src/api_manual/async_cursor.rst new file mode 100644 index 00000000..35283468 --- /dev/null +++ b/doc/src/api_manual/async_cursor.rst @@ -0,0 +1,542 @@ +.. _asynccursorobj: + +************************ +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``. + +.. dbapiobjectextension:: + +.. versionadded:: 2.0.0 + +.. note:: + + AsyncCursor objects are only supported in the python-oracledb Thin mode. + +.. _asynccursormeth: + +AsyncCursor Methods +=================== + +.. method:: AsyncCursor.__aiter__() + + Returns the cursor itself to be used as an asynchronous iterator. + +.. method:: AsyncCursor.__enter__() + + The entry point for the cursor as a context manager. It returns itself. + +.. method:: AsyncCursor.__exit__() + + The exit point for the cursor as a context manager. It closes the cursor. + +.. method:: AsyncCursor.arrayvar(typ, value, [size]) + + A synchronous method that creates an array variable associated with the + cursor of the given type and size and returns a + :ref:`variable object `. The value is either an integer specifying + the number of elements to allocate or it is a list and the number of + elements allocated is drawn from the size of the list. If the value is a + list, the variable is also set with the contents of the list. If the size + is not specified and the type is a string or binary, 4000 bytes is + allocated. This is needed for passing arrays to PL/SQL (in cases where + the list might be empty and the type cannot be determined automatically) or + returning arrays from PL/SQL. + + Array variables can only be used for PL/SQL associative arrays with + contiguous keys. For PL/SQL associative arrays with sparsely populated keys + or for varrays and nested tables, the approach shown in this + `example `__ needs to be used. + +.. method:: AsyncCursor.bindnames() + + A synchronous method that returns the list of bind variable names bound to + the statement. Note that a statement must have been prepared first. + +.. method:: AsyncCursor.callfunc(name, return_type, parameters=None, \ + keyword_parameters=None) + + Calls a PL/SQL function with the given name and returns its value. + + The ``return_type`` parameter for :meth:`~AsyncCursor.callfunc()` is + expected to be a Python type, one of the :ref:`oracledb types ` or + an :ref:`Object Type `. + + The sequence of parameters must contain one entry for each parameter that + the PL/SQL function expects. Any keyword parameters will be included after + the positional parameters. + + Use :meth:`AsyncCursor.var()` to define any OUT or IN OUT parameters, if + necessary. + + See :ref:`plsqlfunc` for examples. + + .. note:: + + In line with the Python DB API, it is not recommended to call + :meth:`AsyncCursor.setinputsizes()` prior to calling + :meth:`~AsyncCursor.callfunc()`. Use :meth:`AsyncCursor.var()` instead. + In existing code that calls :meth:`~AsyncCursor.setinputsizes()`, the + first item in the :meth:`~AsyncCursor.setinputsizes()` parameter list + refers to the return value of the PL/SQL function. + +.. method:: AsyncCursor.callproc(name, parameters=None, keyword_parameters=None) + + Calls a PL/SQL procedure with the given name. + + The sequence of parameters must contain one entry for each parameter that + the procedure expects. The result of the call is a modified copy of the + input sequence. Input parameters are left untouched; output and + input/output parameters are replaced with possibly new values. Keyword + parameters will be included after the positional parameters and are not + returned as part of the output sequence. + + Use :meth:`AsyncCursor.var()` to define any OUT or IN OUT parameters if + necessary. + + No query result set is returned by :meth:`~AsyncCursor.callproc()`. + Instead, use :ref:`REF CURSOR ` parameters or :ref:`Implicit + Results `. + + See :ref:`plsqlproc` for an example. + +.. method:: AsyncCursor.close() + + A synchronous method that closes the cursor now, rather than whenever + ``__del__`` is called. The cursor will be unusable from this point + forward; an Error exception will be raised if any operation is attempted + with the cursor. + +.. method:: AsyncCursor.execute(statement, parameters=None, ** keyword_parameters) + + Executes a statement against the database. See :ref:`sqlexecution`. + + Parameters may be passed as a dictionary or sequence or as keyword + parameters. If the parameters are a dictionary, the values will be bound by + name and if the parameters are a sequence the values will be bound by + position. Note that if the values are bound by position, the order of the + variables is from left to right as they are encountered in the statement + and SQL statements are processed differently than PL/SQL statements. For + this reason, it is generally recommended to bind parameters by name instead + of by position. + + Parameters passed as a dictionary are name and value pairs. The name maps + to the bind variable name used by the statement and the value maps to the + Python value you wish bound to that bind variable. + + A reference to the statement will be retained by the cursor. If *None* or + the same string object is passed in again, the cursor will execute that + statement again without performing a prepare or rebinding and redefining. + This is most effective for algorithms where the same statement is used, but + different parameters are bound to it (many times). Note that parameters + that are not passed in during subsequent executions will retain the value + passed in during the last execution that contained them. + + For maximum efficiency when reusing a statement, it is best to use the + :meth:`AsyncCursor.setinputsizes()` method to specify the parameter types and + sizes ahead of time; in particular, *None* is assumed to be a string of + length 1 so any values that are later bound as numbers or dates will raise + a TypeError exception. + + If the statement is a query, the cursor is returned as a convenience to the + caller (so it can be used directly as an iterator over the rows in the + cursor); otherwise, *None* is returned. + +.. method:: AsyncCursor.executemany(statement, parameters, batcherrors=False, \ + arraydmlrowcounts=False) + + Executes a SQL statement once using all bind value mappings or sequences + found in the sequence parameters. This can be used to insert, update, or + delete multiple rows in a table with a single python-oracledb call. It can + also invoke a PL/SQL procedure multiple times. See :ref:`batchstmnt`. + + The ``statement`` parameter is managed in the same way as the + :meth:`AsyncCursor.execute()` method manages it. + + The ``parameters`` parameter can be a list of tuples, where each tuple item + maps to one bind variable placeholder in ``statement``. It can also be a + list of dictionaries, where the keys match the bind variable placeholder + names in ``statement``. If there are no bind values, or values have + previously been bound, the ``parameters`` value can be an integer + specifying the number of iterations. + + In python-oracledb Thick mode, if the size of the buffers allocated for any + of the parameters exceeds 2 GB, you will receive the error ``DPI-1015: + array size of is too large``. If you receive this error, decrease the + number of rows being inserted. + + When True, the ``batcherrors`` parameter enables batch error support within + Oracle and ensures that the call succeeds even if an exception takes place + in one or more of the sequence of parameters. The errors can then be + retrieved using :meth:`AsyncCursor.getbatcherrors()`. + + When True, the ``arraydmlrowcounts`` parameter enables DML row counts to be + retrieved from Oracle after the method has completed. The row counts can + then be retrieved using :meth:`AsyncCursor.getarraydmlrowcounts()`. + + Both the ``batcherrors`` parameter and the ``arraydmlrowcounts`` parameter + can only be True when executing an insert, update, delete, or merge + statement. In all other cases, an error will be raised. + + For maximum efficiency, it is best to use the + :meth:`AsyncCursor.setinputsizes()` method to specify the parameter types + and sizes ahead of time. In particular, the value *None* is assumed to be a + string of length 1 so any values that are later bound as numbers or dates + will raise a TypeError exception. + +.. method:: AsyncCursor.fetchall() + + Fetches all (remaining) rows of a query result, returning them as a list of + tuples. An empty list is returned if no more rows are available. Note that + the cursor's ``arraysize`` attribute can affect the performance of this + operation, as internally reads from the database are done in batches + corresponding to ``arraysize``. + + An exception is raised if the previous call to + :meth:`AsyncCursor.execute()` did not produce any result set or no call + was issued yet. + +.. method:: AsyncCursor.fetchmany(size=cursor.arraysize) + + Fetches the next set of rows of a query result, returning a list of tuples. + An empty list is returned if no more rows are available. Note that the + cursor's arraysize attribute can affect the performance of this operation. + + The number of rows to fetch is specified by the parameter. If it is not + given, the cursor's arraysize attribute determines the number of rows to be + fetched. If the number of rows available to be fetched is fewer than the + amount requested, fewer rows will be returned. + + An exception is raised if the previous call to + :meth:`AsyncCursor.execute()` did not produce any result set or no call + was issued yet. + +.. method:: AsyncCursor.fetchone() + + Fetches the next row of a query result set, returning a single tuple or + *None* when no more data is available. + + An exception is raised if the previous call to + :meth:`AsyncCursor.execute()` did not produce any result set or no call + was issued yet. + +.. method:: AsyncCursor.getarraydmlrowcounts() + + A synchronous method that retrieves the DML row counts after a call to + :meth:`AsyncCursor.executemany()` with ``arraydmlrowcounts`` enabled. This + will return a list of integers corresponding to the number of rows + affected by the DML statement for each element of the array passed to + :meth:`AsyncCursor.executemany()`. + + .. note:: + + This method is only available for Oracle 12.1 and later. + +.. 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 + failed. The offset can be determined by looking at the offset attribute of + the error object. + +.. method:: AsyncCursor.getimplicitresults() + + A synchronous method that returns a list of cursors which correspond to + implicit results made available from a PL/SQL block or procedure without + the use of OUT ref cursor parameters. The PL/SQL block or procedure opens + the cursors and marks them for return to the driver using the procedure + dbms_sql.return_result. Cursors returned in this fashion should not be + closed. They will be closed automatically by the parent cursor when it is + closed. Closing the parent cursor will invalidate the cursors returned by + this method. + + .. note:: + + This method is only available with Oracle Database 12.1 or later. It is + most like the DB API method nextset(), but unlike that method (which + requires that the next result set overwrite the current result set), + this method returns cursors which can be fetched independently of each + other. + +.. method:: AsyncCursor.parse(statement) + + This can be used to parse a statement without actually executing it + (parsing step is done automatically by Oracle when a statement is + :meth:`executed `). + + .. note:: + + You can parse any DML or DDL statement. DDL statements are executed + immediately and an implied commit takes place. + +.. method:: AsyncCursor.prepare(statement, tag, cache_statement=True) + + A synchronous method that can be used before a call to + :meth:`AsyncCursor.execute()` to define the statement that will be + executed. When this is done, the prepare phase will not be performed when + the call to :meth:`AsyncCursor.execute()` is made with *None* or the same + string object as the statement. + + If the ``tag`` parameter is specified and the ``cache_statement`` parameter + is *True*, the statement will be returned to the statement cache with the + given tag. + + If the ``cache_statement`` parameter is *False*, the statement will be + removed from the statement cache (if it was found there) or will simply not + be cached. + + See :ref:`Statement Caching ` for more information. + +.. method:: AsyncCursor.setinputsizes(*args, **keywordArgs) + + A synchronous method that can be used before a call to + :meth:`AsyncCursor.execute()` and :meth:`AsyncCursor.executemany()` to + predefine memory areas for the operation's parameters. Each parameter + should be a type object corresponding to the data that will be used for a + :ref:`bind variable placeholder ` in the SQL or PL/SQL statement. + Alternatively, it can be an integer specifying the maximum length of a + string bind variable value. + + Use keyword parameters when :ref:`binding by name `. Use + positional parameters when :ref:`binding by position `. The + parameter value can be *None* to indicate that python-oracledb should + determine the required space from the data value provided. + + The parameters or keyword names correspond to the bind variable + placeholders used in the SQL or PL/SQL statement. Note this means that for + use with :meth:`AsyncCursor.executemany()` it does not correspond to the + number of bind value mappings or sequences being passed. + + When repeated calls to :meth:`AsyncCursor.execute()` or + :meth:`AsyncCursor.executemany()` are made binding different string data + lengths, using :meth:`~AsyncCursor.setinputsizes()` can help reduce the + database's SQL "version count" for the statement. See :ref:`Reducing the + SQL Version Count `. + + .. note:: + + :meth:`AsyncCursor.setinputsizes()` should not be used for bind + variables passed to :meth:`AsyncCursor.callfunc()` or + :meth:`AsyncCursor.callproc()`. Instead, use `AsyncCursor.var()`. + + If :meth:`AsyncCursor.setinputsizes()` is used with + :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 + DB API. Python-oracledb automatically allocates as much space as needed to + fetch LONG and LONG RAW columns, and also to fetch CLOB as string and BLOB + as bytes. + +.. method:: AsyncCursor.var(typ, [size, arraysize, inconverter, outconverter, \ + typename, encoding_errors, bypass_decode, convert_nulls]) + + A synchronous method that creates a :ref:`variable object ` with + the specified characteristics. This method can be used for binding to + PL/SQL IN and OUT parameters where the length or type cannot be determined + automatically from the Python variable being bound. It can also be used in + :ref:`input ` and :ref:`output ` + type handlers. + + The ``typ`` parameter specifies the type of data that should be stored in the + variable. This should be one of the :ref:`database type constants + `, :ref:`DB API constants `, an object type returned from + the method :meth:`AsyncConnection.gettype()` or one of the following Python + types: + + .. list-table-with-summary:: + :header-rows: 1 + :class: wy-table-responsive + :align: center + :summary: The first column is the Python Type. The second column is the corresponding Database Type. + + * - Python Type + - Database Type + * - bool + - :attr:`oracledb.DB_TYPE_BOOLEAN` + * - bytes + - :attr:`oracledb.DB_TYPE_RAW` + * - datetime.date + - :attr:`oracledb.DB_TYPE_DATE` + * - datetime.datetime + - :attr:`oracledb.DB_TYPE_DATE` + * - datetime.timedelta + - :attr:`oracledb.DB_TYPE_INTERVAL_DS` + * - decimal.Decimal + - :attr:`oracledb.DB_TYPE_NUMBER` + * - float + - :attr:`oracledb.DB_TYPE_NUMBER` + * - int + - :attr:`oracledb.DB_TYPE_NUMBER` + * - str + - :attr:`oracledb.DB_TYPE_VARCHAR` + + The ``size`` parameter specifies the length of string and raw variables and is + ignored in all other cases. If not specified for string and raw variables, + the value *4000* is used. + + The ``arraysize`` parameter specifies the number of elements the variable will + have. If not specified the bind array size (usually *1*) is used. When a + variable is created in an output type handler this parameter should be set + to the cursor's array size. + + The ``inconverter`` and ``outconverter`` parameters specify methods used for + converting values to/from the database. More information can be found in + the section on :ref:`variable objects`. + + The ``typename`` parameter specifies the name of a SQL object type and must be + specified when using type :data:`oracledb.OBJECT` unless the type object + was passed directly as the first parameter. + + The ``encoding_errors`` parameter specifies what should happen when decoding + byte strings fetched from the database into strings. It should be one of + the values noted in the builtin + `decode `__ + function. + + The ``bypass_decode`` parameter, if specified, should be passed as a + boolean value. Passing a `True` value causes values of database types + :data:`~oracledb.DB_TYPE_VARCHAR`, :data:`~oracledb.DB_TYPE_CHAR`, + :data:`~oracledb.DB_TYPE_NVARCHAR`, :data:`~oracledb.DB_TYPE_NCHAR` and + :data:`~oracledb.DB_TYPE_LONG` to be returned as `bytes` instead of `str`, + meaning that python-oracledb does not do any decoding. See :ref:`Fetching raw + data ` for more information. + + The ``convert_nulls`` parameter, if specified, should be passed as a boolean + value. Passing the value *True* causes the ``outconverter`` to be called + when a null value is fetched from the database; otherwise, the + ``outconverter`` is only called when non-null values are fetched from the + database. + +.. _asynccursorattr: + +AsyncCursor Attributes +====================== + +.. attribute:: AsyncCursor.arraysize + + This read-write attribute can be used to tune the number of rows internally + fetched and buffered by internal calls to the database when fetching rows + from SELECT statements and REF CURSORS. The value can drastically affect + the performance of a query since it directly affects the number of network + round trips between Python and the database. For methods like + :meth:`AsyncCursor.fetchone()` and :meth:`AsyncCursor.fetchall()` it + does not change how many rows are returned to the application. For + :meth:`AsyncCursor.fetchmany()` it is the default number of rows to fetch. + + The attribute is only used for tuning row and SODA document fetches from + the database. It does not affect data inserts. + + Due to the performance benefits, the default ``Cursor.arraysize`` is *100* + instead of the *1* that the Python DB API recommends. + + See :ref:`Tuning Fetch Performance ` for more information. + +.. attribute:: AsyncCursor.bindvars + + This read-only attribute provides the bind variables used for the last + execute. The value will be either a list or a dictionary depending on + whether binding was done by position or name. Care should be taken when + referencing this attribute. In particular, elements should not be removed + or replaced. + +.. 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 + :meth:`AsyncCursor.execute()` method yet. + +.. attribute:: AsyncCursor.fetchvars + + This read-only attribute specifies the list of variables created for the + last query that was executed on the cursor. Care should be taken when + referencing this attribute. In particular, elements should not be removed + or replaced. + +.. attribute:: AsyncCursor.inputtypehandler + + This read-write attribute specifies a method called for each value that is + bound to a statement executed on the cursor and overrides the attribute + with the same name on the connection if specified. The method signature is + handler(cursor, value, arraysize) and the return value is expected to be a + variable object or *None* in which case a default variable object will be + created. If this attribute is *None*, the default behavior will take place + for all values bound to the statements. + +.. attribute:: AsyncCursor.lastrowid + + This read-only attribute returns the rowid of the last row modified by the + cursor. If no row was modified by the last operation performed on the + cursor, the value *None* is returned. + +.. attribute:: AsyncCursor.outputtypehandler + + This read-write attribute specifies a method called for each column that is + to be fetched from this cursor. The method signature is + handler(cursor, metadata) and the return value is expected to be a + :ref:`variable object` or *None* in which case a default variable + object will be created. If this attribute is *None*, then the default + behavior will take place for all columns fetched from this cursor. + + See :ref:`outputtypehandlers`. + +.. attribute:: AsyncCursor.prefetchrows + + This read-write attribute can be used to tune the number of rows that the + python-oracledb fetches when a SELECT statement is executed. This value can + reduce the number of round-trips to the database that are required to fetch + rows but at the cost of additional memory. Setting this value to *0* can be + useful when the timing of fetches must be explicitly controlled. + + The attribute is only used for tuning row fetches from the database. It + does not affect data inserts. + + See :ref:`Tuning Fetch Performance ` for more information. + +.. attribute:: AsyncCursor.rowcount + + This read-only attribute specifies the number of rows that have currently + been fetched from the cursor (for select statements) or that have been + affected by the operation (for insert, update, delete and merge + statements). For all other statements the value is always *0*. If the + cursor or connection is closed, the value returned is *-1*. + +.. attribute:: AsyncCursor.rowfactory + + This read-write attribute specifies a method to call for each row that is + retrieved from the database. Ordinarily, a tuple is returned for each row + but if this attribute is set, the method is called with the tuple that + would normally be returned, and the result of the method is returned + instead. + + See :ref:`rowfactories`. + +.. attribute:: AsyncCursor.scrollable + + This read-write boolean attribute specifies whether the cursor can be + scrolled or not. By default, cursors are not scrollable, as the server + resources and response times are greater than nonscrollable cursors. This + attribute is checked and the corresponding mode set in Oracle when calling + the method :meth:`AsyncCursor.execute()`. diff --git a/doc/src/api_manual/async_lob.rst b/doc/src/api_manual/async_lob.rst new file mode 100644 index 00000000..1194f8ba --- /dev/null +++ b/doc/src/api_manual/async_lob.rst @@ -0,0 +1,99 @@ +.. _asynclobobj: + +********************* +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. + +.. dbapiobjectextension:: + +See :ref:`lobdata` for more information about using LOBs. + +.. note:: + + AsyncLOB objects are only supported in the python-oracledb Thin mode. + +.. _asynclobmeth: + +AsyncLOB Methods +================ + +.. method:: AsyncLOB.close() + + Closes the LOB. Call this when writing is completed so that the indexes + associated with the LOB can be updated -- but only if :meth:`~AsyncLOB.open()` + was called first. + +.. method:: AsyncLOB.fileexists() + + Returns a boolean indicating if the file referenced by the BFILE type LOB + exists. + +.. method:: AsyncLOB.getchunksize() + + Returns the chunk size for the internal LOB. Reading and writing to the LOB + in chunks of multiples of this size will improve performance. + +.. method:: AsyncLOB.getfilename() + + Returns a two-tuple consisting of the directory alias and file name for a + BFILE type LOB. + +.. method:: AsyncLOB.isopen() + + Returns a boolean indicating if the LOB has been opened using the method + :meth:`~AsyncLOB.open()`. + +.. method:: AsyncLOB.open() + + Opens the LOB for writing. This will improve performance when writing to a + LOB in chunks and there are functional or extensible indexes associated + with the LOB. If this method is not called, each write will perform an open + internally followed by a close after the write has been completed. + +.. method:: AsyncLOB.read([offset=1, [amount]]) + + Returns a portion (or all) of the data in the LOB object. Note that the + amount and offset are in bytes for BLOB and BFILE type LOBs and in UCS-2 + code points for CLOB and NCLOB type LOBs. UCS-2 code points are equivalent + to characters for all but supplemental characters. If supplemental + characters are in the LOB, the offset and amount will have to be chosen + carefully to avoid splitting a character. + +.. method:: AsyncLOB.setfilename(dir_alias, name) + + Sets the directory alias and name of the BFILE type LOB. + +.. method:: AsyncLOB.size() + + Returns the size of the data in the LOB object. For BLOB and BFILE type + LOBs, this is the number of bytes. For CLOB and NCLOB type LOBs, this is the + number of UCS-2 code points. UCS-2 code points are equivalent to characters + for all but supplemental characters. + +.. method:: AsyncLOB.trim(new_size=0) + + Trims the LOB to the new size. + +.. method:: AsyncLOB.write(data, offset=1) + + Writes the data to the LOB object at the given offset. The offset is in + bytes for BLOB type LOBs and in UCS-2 code points for CLOB and NCLOB type + LOBs. UCS-2 code points are equivalent to characters for all but + supplemental characters. If supplemental characters are in the LOB, the + offset will have to be chosen carefully to avoid splitting a character. + Note that if you want to make the LOB value smaller, you must use the + :meth:`~AsyncLOB.trim()` function. + +.. _asynclobattr: + +AsyncLOB Attributes +=================== + +.. attribute:: AsyncLOB.type + + This read-only attribute returns the type of the LOB as one of the + :ref:`database type constants `. diff --git a/doc/src/api_manual/connect_param.rst b/doc/src/api_manual/connect_param.rst deleted file mode 100644 index 8dda4e61..00000000 --- a/doc/src/api_manual/connect_param.rst +++ /dev/null @@ -1,327 +0,0 @@ -.. _connparam: - -************************** -API: ConnectParams Objects -************************** - -.. note:: - - This object is an extension to the DB API. - -These objects are created by :meth:`oracledb.ConnectParams()`. See -:ref:`usingconnparams` for more information. - -.. _connparamsmeth: - -ConnectParams Methods -===================== - -.. method:: ConnectParams.copy() - - Creates a copy of the ConnectParams instance and returns it. - -.. method:: ConnectParams.get_connect_string() - - Returns the connection string associated with the ConnectParams instance. - -.. method:: ConnectParams.parse_connect_string(connect_string) - - Parses the connect string into its components and stores the parameters. - - The ``connect string`` parameter can be an Easy Connect string, name-value - pairs, or a simple alias which is looked up in ``tnsnames.ora``. Parameters - that are found in the connect string override any currently stored values. - -.. 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, \ - 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, handle=None) - - Sets one or more of the parameters. - - -.. _connparamsattr: - -ConnectParams Attributes -======================== - -.. attribute:: ConnectParams.appcontext - - This read-only attribute is a list that specifies the application context used by - the connection. It is a list of 3-tuples that includes the namespace, name, and value. - Each entry in the tuple is a string. - - This attribute is only supported in the python-oracledb Thick mode. - -.. attribute:: ConnectParams.cclass - - This read-only attribute is a string that specifies the connection class - to use for Database Resident Connection Pooling (DRCP). - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. 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 the python-oracledb Thin mode. - - For the python-oracledb Thick mode, use the ``config_dir`` parameter of - :func:`oracledb.init_oracle_client`. - -.. attribute:: ConnectParams.debug_jdwp - - This read-only attribute is a string with the format "host=;port=" - that specifies the host and port of the PL/SQL debugger. This allows the - Java Debug Wire Protocol (JDWP) to debug the PL/SQL code invoked by the - python-oracledb driver. The default value is the value of the environment - variable ``ORA_DEBUG_JDWP``. - - This attribute is only supported in the python-oracledb Thin mode. For - the python-oracledb Thick mode, set the ``ORA_DEBUG_JDWP`` environment - variable which has the same syntax. See :ref:`applntracing` for more - information. - -.. attribute:: ConnectParams.disable_oob - - This read-only attribute is a boolean that indicates whether out-of-band - breaks should be disabled. The default value is False. Note that this value - has no effect on Windows, which does not support this functionality. - - This attribute is only supported in the python-oracledb Thin mode. - - For the python-oracledb Thick mode, set the equivalent option in a - ``sqlnet.ora`` file. - -.. attribute:: ConnectParams.edition - - This read-only attribute is a string that specifies the edition to use - for the connection. This attribute cannot be used simultaneously with the - :attr:`ConnectParams.cclass` attribute. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.events - - This read-only attribute is a boolean that specifies whether the events mode - should be enabled. - - This attribute is needed for continuous query notification (CQN) and high - availability event notifications. The default value is False. - - This attribute is only supported in the python-oracledb Thick mode. - -.. attribute:: ConnectParams.expire_time - - This read-only attribute is an integer that returns the number of minutes - between the sending of keepalive probes. - The default value is 0. If this attribute is set to a value greater than zero, - it enables keepalive. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.externalauth - - This read-only attribute is a boolean that specifies whether external - authentication should be used. The default value is False. - - 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. - - This attribute is only supported in the python-oracledb Thick mode. - -.. attribute:: ConnectParams.host - - This read-only attribute is a string that returns the name or IP address of - the machine hosting the database. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.https_proxy - - This read-only attribute is a string that returns the name or IP address of - a proxy host that is to be used for tunneling secure connections. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.https_proxy_port - - This read-only attribute is an integer that returns the port to be used to - communicate with the proxy host. - The default value is 0. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. 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. - - This attribute is only supported in the python-oracledb Thick mode. - -.. attribute:: ConnectParams.mode - - This read-only attribute is an integer that specifies the authorization mode - to use. - The default value is :data:`~oracledb.AUTH_MODE_DEFAULT`. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. 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. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.protocol - - This read-only attribute is a string that indicates whether unencrypted network - traffic or encrypted network traffic (TLS) is used and it can have the value - tcp or tcps. - The default value is tcp. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.proxy_user - - This read-only attribute is a string that specifies the name of the proxy user to connect to. - If this value is not specified, then it will be parsed out of the user if the user attribute - is in the form "user[proxy_user]". - - This attribute is supported in the python-oracledb Thin and Thick modes. - - -.. attribute:: ConnectParams.purity - - This read-only attribute is an integer that returns the purity used for DRCP. - When the value of this attribute is :attr:`oracledb.PURITY_DEFAULT`, then any - standalone connection will use :attr:`oracledb.PURITY_NEW` and any pooled - connection will use :attr:`oracledb.PURITY_SELF`. The default value is - :data:`~oracledb.PURITY_DEFAULT`. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.retry_count - - This read-only attribute is an integer that returns the number of times that a - connection attempt should be retried before the attempt is terminated. - The default value is 0. - - This attribute is supported in the 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 0. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.server_type - - This read-only attribute is a string that returns the type of server connection - that should be established. If specified, it should be one of `dedicated`, `shared`, - or `pooled`. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.service_name - - This read-only attribute is a string that returns the service name of the database. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.shardingkey - - This read-only attribute is a list that specifies a sequence of strings, numbers, - bytes, or dates that identify the database shard to connect to. - - This attribute is only supported in the python-oracledb Thick mode. - -.. attribute:: ConnectParams.sid - - This read-only attribute is a string that returns the SID of the database. - It is recommended to use the :attr:`ConnectParams.service_name` instead. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.ssl_server_cert_dn - - This read-only attribute is a string that returns the distinguished name (DN), - which should be matched with the server. If this value is specified, then it is - used for any verification. Otherwise, the hostname will be used. - - This value is ignored if the :attr:`~ConnectParams.ssl_server_dn_match` - attribute is not set to the value `True`. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.ssl_server_dn_match - - This read-only attribute is a boolean that indicates whether the server certificate - distinguished name (DN) should be matched in addition to the regular - certificate verification that is performed. The default value is True. - - Note that if the :attr:`~ConnectParams.ssl_server_cert_dn` attribute is not specified, - then host name matching is performed instead. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.stmtcachesize - - This read-only attribute is an integer that identifies the initial size of - the statement cache. The default is the value of - :attr:`defaults.stmtcachesize`. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.supershardingkey - - This read-only attribute is a list that specifies a sequence of strings, numbers, - bytes, or dates that identify the database shard to connect to. - - This attribute is only supported in python-oracledb Thick mode. - -.. attribute:: ConnectParams.tag - - This read-only attribute is a string that identifies the type of connection that - should be returned from a pool. - - This attribute is only supported in python-oracledb Thick mode. - -.. attribute:: ConnectParams.tcp_connect_timeout - - This read-only attribute is a float that indicates the maximum number of seconds - to wait for a connection to be established to the database host. - The default value is 60.0. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.user - - This read-only attribute is a string that specifies the name of the user to - connect to. - - This attribute is supported in the python-oracledb Thin and Thick modes. - -.. attribute:: ConnectParams.wallet_location - - This read-only attribute is a string that specifies the directory where the - wallet can be found. - - In python-oracledb Thin mode, this attribute is the directory containing the - PEM-encoded wallet file, ewallet.pem. In python-oracledb Thick mode, this - attribute is the directory containing the file, cwallet.sso. - - This attribute is supported in the python-oracledb Thin and Thick modes. diff --git a/doc/src/api_manual/connect_params.rst b/doc/src/api_manual/connect_params.rst new file mode 100644 index 00000000..ad09094b --- /dev/null +++ b/doc/src/api_manual/connect_params.rst @@ -0,0 +1,610 @@ +.. _connparam: + +************************** +API: ConnectParams Objects +************************** + +The ConnectParams objects are created by :meth:`oracledb.ConnectParams()`. +See :ref:`usingconnparams` for more information. + +.. dbapiobjectextension:: + +.. _connparamsmeth: + +ConnectParams Methods +===================== + +.. method:: ConnectParams.copy() + + Creates a copy of the ConnectParams instance and returns it. + +.. method:: ConnectParams.get_connect_string() + + Returns the connection string associated with the ConnectParams instance. + +.. method:: ConnectParams.get_network_service_names() + + Returns a list of the network service names found in the + :ref:`tnsnames.ora ` file which is inside the directory + that can be identified by the attribute :attr:`~ConnectParams.config_dir`. + If a tnsnames.ora file does not exist, then an exception is raised. + +.. method:: ConnectParams.parse_connect_string(connect_string) + + Parses the connect string into its components and stores the parameters. + + The ``connect string`` parameter can be an Easy Connect string, name-value + pairs, or a simple alias which is looked up in ``tnsnames.ora``. Parameters + that are found in the connect string override any currently stored values. + +.. method:: ConnectParams.parse_dsn_with_credentials(dsn) + + 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*. + + .. versionadded:: 1.3.0 + +.. method:: ConnectParams.set(user=None, proxy_user=None, password=None, \ + newpassword=None, wallet_password=None, access_token=None, host=None, \ + port=None, protocol=None, https_proxy=None, https_proxy_port=None, \ + service_name=None, instance_name=None, sid=None, server_type=None, \ + cclass=None, purity=None, expire_time=None, retry_count=None, \ + retry_delay=None, tcp_connect_timeout=None, ssl_server_dn_match=None, \ + ssl_server_cert_dn=None, wallet_location=None, events=None, \ + externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, \ + edition=None, tag=None, matchanytag=None, config_dir=None, \ + appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ + connection_id_prefix=None, ssl_context=None, sdu=None, \ + pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ + program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ + terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ + driver_name=oracledb.defaults.driver_name, use_sni=None, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, 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 + ``driver_name`` parameters were added. Support for ``edition`` and + ``appcontext`` was added to python-oracledb Thin mode. + + .. versionchanged:: 2.3.0 + + The ``ssl_version`` parameter was added. + + .. versionchanged:: 2.1.0 + + The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. + + .. versionchanged:: 2.0.0 + + The ``ssl_context`` and ``sdu`` parameters were added. + + .. versionchanged:: 1.4.0 + + The ``connection_id_prefix`` parameter was added. + +.. method:: ConnectParams.set_from_config(config) + + Sets the property values based on the specified configuration. This method + is intended for use with Centralized Configuration Providers. + + The ``config`` parameter is a dictionary which consists of the following + optional keys: "connect_descriptor", "user", "password", and "pyo". + + If the key "connect_descriptor" is specified, it is expected to be a + string, which will be parsed and the properties found within it are stored + in the ConnectParams instance. + + If the keys "user" or "password" are specified, and the parameters do not + already have a user or password set, these values will be stored; + otherwise, they will be ignored. The key "user" is expected to be a + string. The "key" password may be a string or it may be a dictionary which + will be examined by a :ref:`registered password type handler + ` to determine the actual password. + + If the key "pyo" is specified, it is expected to be a dictionary containing + keys corresponding to property names. Any property names accepted by the + ConnectParams class will be stored in the ConnectParams instance; all other + values will be ignored. + + .. versionadded:: 3.0.0 + +.. _connparamsattr: + +ConnectParams Attributes +======================== + +.. attribute:: ConnectParams.appcontext + + This read-only attribute is a list that specifies the application context + used by the connection. It is a list of 3-tuples that includes the + namespace, name, and value. Each entry in the tuple is a string. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.cclass + + This read-only attribute is a string that specifies the connection class + to use for :ref:`drcp`. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.config_dir + + This read-only attribute is a string that identifies the directory in which + the :ref:`optional configuration files ` are found. The + default is the value of :attr:`defaults.config_dir`. + +.. attribute:: ConnectParams.connection_id_prefix + + This read-only attribute is a string that is added to the beginning of the + generated ``connection_id`` that is sent to the database for + `tracing `__. + + This attribute is only supported in python-oracledb Thin mode. + + .. versionadded:: 1.4.0 + +.. attribute:: ConnectParams.debug_jdwp + + This read-only attribute is a string with the format + "host=;port=" that specifies the host and port of the PL/SQL + debugger. This allows the Java Debug Wire Protocol (JDWP) to debug the + PL/SQL code invoked by the python-oracledb driver. The default value is the + value of the environment variable ``ORA_DEBUG_JDWP``. + + This attribute is only supported in python-oracledb Thin mode. + + For python-oracledb Thick mode, set the ``ORA_DEBUG_JDWP`` environment + variable which has the same syntax. See :ref:`applntracing` for more + information. + +.. attribute:: ConnectParams.disable_oob + + This read-only attribute is a boolean that indicates whether out-of-band + breaks should be disabled. The default value is *False*. Note that this + value has no effect on Windows, which does not support this functionality. + + This attribute is only supported in python-oracledb Thin mode. + + For python-oracledb Thick mode, set the equivalent option in a + ``sqlnet.ora`` file. + +.. attribute:: ConnectParams.driver_name + + This read-only attribute is a string that specifies the driver used by the + client to connect to Oracle Database. This is an arbitrary value set by the + user in the :meth:`oracledb.ConnectParams()` method or the + :attr:`defaults.driver_name` attribute which is the default value. This is + the value shown in the CLIENT_DRIVER column of the + V$SESSION_CONNECT_INFO view. + + This attribute is supported in both python-oracledb Thin and Thick modes. + + .. versionadded:: 2.5.0 + +.. attribute:: ConnectParams.edition + + This read-only attribute is a string that specifies the edition to use + for the connection. This attribute cannot be used simultaneously with the + :attr:`ConnectParams.cclass` attribute. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.events + + This read-only attribute is a boolean that specifies whether the events + mode should be enabled. + + This attribute is needed for continuous query notification (CQN) and high + availability event notifications. The default value is *False*. + + This attribute is only supported in python-oracledb Thick mode. + +.. attribute:: ConnectParams.expire_time + + This read-only attribute is an integer that returns the number of minutes + between the sending of keepalive probes. + + The default value is *0*. If this attribute is set to a value greater than + zero, it enables keepalive. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.externalauth + + This read-only attribute is a boolean that specifies whether external + authentication should be used. The default value is *False*. + + 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. + + 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 + the machine hosting the database. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.https_proxy + + This read-only attribute is a string that returns the name or IP address of + a proxy host that is to be used for tunneling secure connections. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.https_proxy_port + + This read-only attribute is an integer that returns the port to be used to + communicate with the proxy host. The default value is *0*. + + 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 + the client connecting to Oracle Database. This is an arbitrary value set + by the user in the :meth:`oracledb.ConnectParams()` method or the + :attr:`defaults.machine` attribute which is the default value. This is the + value shown in the MACHINE column of the V$SESSION view. + + This attribute is only supported in python-oracledb Thin mode. + + .. versionadded:: 2.5.0 + +.. 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*. + + This attribute is only supported in python-oracledb Thick mode. + +.. attribute:: ConnectParams.mode + + This read-only attribute is an integer that specifies the authorization mode + to use. The default value is :data:`~oracledb.AUTH_MODE_DEFAULT`. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.osuser + + This read-only attribute is a string that represents the operating system + user that initiates the database connection. This is an arbitrary value + set by the user in the :meth:`oracledb.ConnectParams()` method or the + :attr:`defaults.osuser` attribute which is the default value. This is the + value shown in the OSUSER column of the V$SESSION view. + + This attribute is only supported in python-oracledb Thin mode. + + .. versionadded:: 2.5.0 + +.. attribute:: ConnectParams.pool_boundary + + This read-only attribute is one of the strings *statement* or *transaction* + which indicates when pooled :ref:`DRCP ` or PRCP connections can be + returned to the pool. If the value is *statement*, then pooled DRCP or PRCP + connections are implicitly released back to the DRCP or PRCP pool when the + connection is stateless (that is, there are no active cursors, active + transactions, temporary tables, or temporary LOBs). If the value is + *transaction*, then pooled DRCP or PRCP connections are implicitly released + back to the DRCP or PRCP pool when either one of the methods + :meth:`Connection.commit()` or :meth:`Connection.rollback()` are called. + This attribute requires the use of DRCP or PRCP with Oracle Database 23ai + (or later). See :ref:`implicitconnpool` for more information. + + This attribute is supported in both python-oracledb Thin and Thick modes. + + .. 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*. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.program + + This read-only attribute is a string that specifies the name of the + executable program or application connected to Oracle Database. This is an + arbitrary value set by the user in the :meth:`oracledb.ConnectParams()` + method or the :attr:`defaults.program` attribute which is the default + value. This is the value shown in the PROGRAM column of the + V$SESSION view. + + This attribute is supported in python-oracledb Thin mode. + + .. versionadded:: 2.5.0 + +.. attribute:: ConnectParams.protocol + + This read-only attribute is a string that indicates whether unencrypted + network traffic or encrypted network traffic (TLS) is used and it can have + the value *tcp* or *tcps*. The default value is *tcp*. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.proxy_user + + This read-only attribute is a string that specifies the name of the proxy + user to connect to. If this value is not specified, then it will be parsed + out of the user if the user attribute is in the form "user[proxy_user]". + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.purity + + This read-only attribute is an integer that returns the purity used for + :ref:`drcp`. When the value of this attribute is + :attr:`oracledb.PURITY_DEFAULT`, then any standalone connection will use + :attr:`oracledb.PURITY_NEW` and any pooled connection will use + :attr:`oracledb.PURITY_SELF`. The default value is + :data:`~oracledb.PURITY_DEFAULT`. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.retry_count + + This read-only attribute is an integer that returns the number of times + that a connection attempt should be retried before the attempt is + terminated. The default value is *0*. + + 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*. + + 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* + second. + +.. attribute:: ConnectParams.sdu + + This read-only attribute is an integer that returns the requested size of + the Session Data Unit (SDU), in bytes. The value tunes internal buffers + used for communication to the database. Bigger values can increase + throughput for large queries or bulk data loads, but at the cost of higher + memory use. The SDU size that will actually be used is negotiated down to + the lower of this value and the database network SDU configuration value. + See the `Database Net Services documentation + `__ for more details. + + This attribute is supported in both python-oracledb Thin and Thick modes. + + .. versionadded:: 2.0.0 + +.. attribute:: ConnectParams.server_type + + This read-only attribute is a string that returns the type of server + connection that should be established. If specified, it should be one of + *dedicated*, *shared*, or *pooled*. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.service_name + + This read-only attribute is a string that returns the service name of the + database. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.shardingkey + + This read-only attribute is a list that specifies a sequence of strings, + numbers, bytes, or dates that identify the database shard to connect to. + See :ref:`connsharding`. + + This attribute is only supported in python-oracledb Thick mode. + +.. attribute:: ConnectParams.sid + + This read-only attribute is a string that returns the SID of the database. + It is recommended to use the :attr:`ConnectParams.service_name` instead. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.ssl_context + + This read-only attribute is an `SSLContext object + `__ which is used + for connecting to the database using TLS. This SSL context will be modified + to include the private key or any certificates found in a separately + supplied wallet. This parameter should only be specified if the default + SSLContext object cannot be used. + + This attribute is only supported in python-oracledb Thin mode. + + .. versionadded:: 2.0.0 + +.. attribute:: ConnectParams.ssl_server_cert_dn + + This read-only attribute is a string that returns the distinguished name + (DN), which should be matched with the server. If this value is specified, + then it is used for any verification. Otherwise, the hostname will be used. + + This value is ignored if the :attr:`~ConnectParams.ssl_server_dn_match` + attribute is not set to the value *True*. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.ssl_server_dn_match + + This read-only attribute is a boolean that indicates whether the server + certificate distinguished name (DN) should be matched in addition to the + regular certificate verification that is performed. The default value is + *True*. + + Note that if the :attr:`~ConnectParams.ssl_server_cert_dn` attribute is not + specified, then host name matching is performed instead. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.ssl_version + + This read-only attribute is one of the constants *ssl.TLSVersion.TLSv1_2* + or *ssl.TLSVersion.TLSv1_3* which identifies the TLS protocol version + used. These constants are defined in the Python `ssl `__ module. + + This attribute is supported in both python-oracledb Thin and Thick modes. + + .. versionadded:: 2.3.0 + +.. attribute:: ConnectParams.stmtcachesize + + This read-only attribute is an integer that identifies the initial size of + the statement cache. The default is the value of + :attr:`defaults.stmtcachesize`. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.supershardingkey + + This read-only attribute is a list that specifies a sequence of strings, + numbers, bytes, or dates that identify the database shard to connect to. + See :ref:`connsharding`. + + This attribute is only supported in python-oracledb Thick mode. + +.. attribute:: ConnectParams.tag + + This read-only attribute is a string that identifies the type of connection + that should be returned from a pool. + + This attribute is only supported in python-oracledb Thick mode. + +.. attribute:: ConnectParams.tcp_connect_timeout + + This read-only attribute is a float that indicates the maximum number of + seconds to wait for a connection to be established to the database host. + The default value is *20.0*. + + 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. + +.. 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 + + This read-only attribute is a string that specifies the terminal + identifier from which the connection originates. This is an arbitrary value + set by the user in the :meth:`oracledb.ConnectParams()` method or the + :attr:`defaults.terminal` attribute which is the default value. This is the + value shown in the TERMINAL column of the V$SESSION view. + + This attribute is only supported in python-oracledb Thin mode. + + .. 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 + an `Oracle Autonomous Database Serverless (ADB-S) + `__ + specific feature that can reduce the latency in round-trips to the database + after a connection has been established. This feature is only available + with certain versions of ADB-S. The default value is *False*. + + This attribute is supported in both python-oracledb Thin and Thick modes. + + .. versionadded:: 2.1.0 + +.. attribute:: ConnectParams.user + + This read-only attribute is a string that specifies the name of the user to + connect to. + + This attribute is supported in both python-oracledb Thin and Thick modes. + +.. attribute:: ConnectParams.wallet_location + + This read-only attribute is a string that specifies the directory where the + wallet can be found. + + In python-oracledb Thin mode, this attribute is the directory containing + the PEM-encoded wallet file, ewallet.pem. In python-oracledb Thick mode, + this attribute is the directory containing the file, cwallet.sso. + + 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 70786eda..2d70fef2 100644 --- a/doc/src/api_manual/connection.rst +++ b/doc/src/api_manual/connection.rst @@ -4,7 +4,8 @@ API: Connection Objects *********************** -A Connection object can be created with :meth:`oracledb.connect()`. +A Connection object can be created with :meth:`oracledb.connect()` or with +:meth:`ConnectionPool.acquire()`. .. note:: @@ -19,20 +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]) @@ -49,27 +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 transaction. - - .. note:: - - This method is an extension to the DB API definition. + Breaks a long-running statement. + .. 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() @@ -90,20 +78,107 @@ Connection Methods Commits any pending transactions to the database. -.. method:: Connection.createlob(lobType) +.. method:: Connection.createlob(lob_type, data=None) Creates and returns a new temporary :ref:`LOB object ` of the - specified type. The ``lobType`` parameter should be one of - :data:`oracledb.CLOB`, :data:`oracledb.BLOB` or :data:`oracledb.NCLOB`. + specified type. The ``lob_type`` parameter should be one of + :data:`oracledb.DB_TYPE_CLOB`, :data:`oracledb.DB_TYPE_BLOB`, or + :data:`oracledb.DB_TYPE_NCLOB`. - .. note:: + If data is supplied, it will be written to the temporary LOB before it is + returned. + + .. versionchanged:: 2.0 - This method is an extension to the DB API definition. + The parameter ``data`` was added. -.. method:: Connection.cursor() + .. dbapimethodextension:: + +.. method:: Connection.cursor(scrollable=False) Returns a new :ref:`cursor object ` using the connection. +.. 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. + + .. versionadded:: 2.1.0 + +.. method:: Connection.encode_oson(value) + + Encodes a Python value into `OSON-encoded `__ + bytes and returns them. This is useful for inserting into columns which + have the check constraint ``IS JSON FORMAT OSON`` enabled. + + .. 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 @@ -113,40 +188,39 @@ 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 standalone connection. Pooled connections internally perform this - check before returning a connection to the application. + existing :ref:`standalone connections `. For pooled + connections, the :meth:`ConnectionPool.acquire()` method internally + performs this check before returning a connection to the application, see + :ref:`poolhealth`. - 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 @@ -155,33 +229,35 @@ 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. - .. note:: + This function performs a :ref:`round-trip ` to the database, so + it should not be used unnecessarily. - This method is an extension to the DB API definition. + Note connection pools will perform the same health check automatically, + based on configuration settings. See :ref:`poolhealth`. + Also, see :meth:`Connection.is_healthy()` for a lightweight alternative. + + .. 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) @@ -197,24 +273,21 @@ 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() Rolls back any pending transactions. - .. 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: :: @@ -228,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: @@ -258,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, \ @@ -272,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. @@ -313,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 @@ -333,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:: @@ -352,62 +420,78 @@ Connection Methods explicitly closed using the function :meth:`~Connection.close()`, the subscription will not be deregistered in the database. -.. method:: Connection.tpc_begin(xid, flags) +.. method:: Connection.tpc_begin(xid, flags, timeout) Begins a Two-Phase Commit (TPC) on a global transaction using the specified transaction identifier (xid). - The ``xid`` parameter should be an object returned by the :meth:`~Connection.xid()` - method. + The ``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 following code sample demonstrates the ``tpc_begin()`` function:: - connection.tpc_begin(xid=x, flags=oracledb.TPC_BEGIN_NEW) x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + connection.tpc_begin(xid=x, flags=oracledb.TPC_BEGIN_NEW, timeout=30) - See :ref:`tcp` for information on TPC. + See :ref:`tpc` for information on TPC. .. method:: Connection.tpc_commit(xid, one_phase) - Commits a global transaction. When called with no arguments, this method commits - a transaction previously prepared with :meth:`~Connection.tpc_begin()` and optionally - prepared with :meth:`~Connection.tpc_prepare()`. If :meth:`~Connection.tpc_prepare()` - is not called, a single phase commit is performed. A transaction manager may choose - to do this if only a single resource is participating in the global transaction. + 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:: - connection.tpc_commit(xid=x, one_phase=False) x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + connection.tpc_commit(xid=x, one_phase=False) - See :ref:`tcp` for information on TPC. + See :ref:`tpc` for information on TPC. .. method:: Connection.tpc_end(xid, flags) - Ends or suspends work on a global transaction. This function is only intended - for use by transaction managers. + 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 @@ -415,25 +499,25 @@ Connection Methods The following code sample demonstrates the ``tpc_end()`` function:: - connection.tpc_end(xid=x, flags=oracledb.TPC_END_NORMAL) x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + connection.tpc_end(xid=x, flags=oracledb.TPC_END_NORMAL) - See :ref:`tcp` for information on TPC. + See :ref:`tpc` for information on TPC. .. method:: Connection.tpc_forget(xid) - Causes the database to forget a heuristically completed TPC transaction. This - function is only intended to be called by transaction managers. + 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:: - connection.tpc_forget(xid=x) x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + connection.tpc_forget(xid=x) - See :ref:`tcp` for information on TPC. + See :ref:`tpc` for information on TPC. .. method:: Connection.tpc_prepare(xid) @@ -442,55 +526,58 @@ 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:: - connection.tpc_prepare(xid=x) x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + connection.tpc_prepare(xid=x) - See :ref:`tcp` for information on TPC. + See :ref:`tpc` for information on TPC. .. method:: Connection.tpc_recover() - Returns a list of pending transaction identifiers that require recovery. Objects of - type ``Xid`` (as returned by the :meth:`~Connection.xid()` function) are returned and - these can be passed to :meth:`~Connection.tpc_commit()` or :meth:`~Connection.tpc_rollback()` - as needed. + 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:: connection.tpc_recover() - See :ref:`tcp` for information on TPC. + See :ref:`tpc` for information on TPC. .. method:: Connection.tpc_rollback(xid) Rolls back a global transaction. - If an ``xid`` parameter is not passed, then it rolls back the transaction that was previously - started with :meth:`~Connection.tpc_begin()`. + If an ``xid`` parameter is 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:: - connection.tpc_rollback(xid=x) x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") + connection.tpc_rollback(xid=x) - See :ref:`tcp` for information on TPC. + See :ref:`tpc` for information on TPC. .. method:: Connection.unsubscribe(subscr) @@ -509,19 +596,21 @@ 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:: connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1") - See :ref:`tcp` for information on TPC. + See :ref:`tpc` for information on TPC. .. _connattrs: @@ -530,14 +619,11 @@ Connection Attributes .. attribute:: Connection.action - This write-only attribute sets the action column in the v$session table. It - is a string attribute and cannot be set to None -- use the empty string - instead. - - .. note:: - - This attribute is an extension to the DB API definition. + This write-only attribute sets the ACTION column in the V$SESSION view. It + is a string attribute but the value *None* is accepted and treated as an + empty string. + .. dbapiattributeextension:: .. attribute:: Connection.autocommit @@ -545,48 +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. - If a timeout occurs, the error *DPI-1067* will be returned if the - connection is still usable. Alternatively the error *DPI-1080* will be + 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 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 table. - - .. note:: - - This attribute is an extension to the DB API definition. + This write-only attribute sets the CLIENT_IDENTIFIER column in the + V$SESSION view. + .. dbapiattributeextension:: .. attribute:: Connection.clientinfo - This write-only attribute sets the client_info column in the v$session - table. + 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 @@ -596,167 +675,237 @@ 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:: + .. dbapiattributeextension:: - This attribute is an extension to the DB API definition. +.. attribute:: Connection.db_domain -.. attribute:: Connection.dbop + This read-only attribute specifies the Oracle Database domain name + associated with the connection. It is the same value returned by the SQL + ``SELECT value FROM V$PARAMETER WHERE NAME = 'db_domain'``. - This write-only attribute sets the database operation that is to be - monitored. This can be viewed in the ``DBOP_NAME`` column of the - ``V$SQL_MONITOR`` table. + .. dbapiattributeextension:: - .. note:: + .. versionadded:: 2.0.0 - This attribute is an extension to the DB API definition. +.. attribute:: Connection.db_name -.. attribute:: Connection.dsn - - This read-only attribute returns the TNS entry of the database to which a - connection has been established. + This read-only attribute specifies the Oracle Database name associated with + the connection. It is the same value returned by the SQL + ``SELECT NAME FROM V$DATABASE``. - .. note:: + .. dbapiattributeextension:: - This attribute is an extension to the DB API definition. + .. versionadded:: 2.0.0 -.. attribute:: Connection.econtext_id +.. attribute:: Connection.dbop - This write-only attribute specifies the execution context id. This - value can be found as ecid in the v$session table and econtext_id in the - auditing tables. The maximum length is 64 bytes. + This write-only attribute sets the database operation that is to be + monitored. This can be viewed in the DBOP_NAME column of the + V$SQL_MONITOR view. -.. attribute:: Connection.edition + .. dbapiattributeextension:: - This read-only attribute gets the session edition and is only available in - Oracle Database 11.2 (both client and server must be at this level or - higher for this to work). +.. attribute:: Connection.dsn - .. note:: + This read-only attribute returns the TNS entry of the database to which a + connection has been established. - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: -.. attribute:: Connection.encoding +.. attribute:: Connection.econtext_id - This read-only attribute returns the IANA character set name of the - character set in use by the Oracle client for regular strings. The - encodings in use are always UTF-8. + This write-only attribute specifies the execution context id. This value + can be found as the ECID column in the V$SESSION view and ECONTEXT_ID in + the auditing tables. The maximum length is 64 bytes. - .. deprecated:: cx_Oracle 8.2 +.. attribute:: Connection.edition - .. note:: + This read-only attribute gets the session edition and is only available + with Oracle Database 11.2, or later. - 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 - This read-only attribute returns the Oracle Call Interface (OCI) service context handle for the - connection. It is primarily provided to facilitate testing the creation of - a connection using the OCI service context handle. + This read-only attribute returns the Oracle Call Interface (OCI) service + context handle for the connection. It is primarily provided to facilitate + testing the creation of a connection using the OCI service context handle. 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. - .. note:: + See :ref:`inputtypehandlers`. - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: +.. attribute:: Connection.instance_name + + This read-only attribute specifies the Oracle Database instance name + associated with the connection. It is the same value as the SQL expression + ``sys_context('userenv', 'instance_name')``. + + .. dbapiattributeextension:: + + .. versionadded:: 1.4.0 .. 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. - .. note: + 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. - 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. + .. dbapiattributeextension:: + .. versionchanged:: 3.0.0 -.. attribute:: Connection.maxBytesPerCharacter + This attribute was added to python-oracledb Thin mode. - This deprecated, read-only attribute returns the value 4 since encodings - are always UTF-8. +.. attribute:: Connection.max_identifier_length - Previously it returned the maximum number of bytes each character can use - for the client character set. + This read-only attribute specifies the maximum database identifier length + in bytes supported by the database to which the connection has been + established. See `Database Object Naming Rules + `__. The value may be + *None*, *30*, or *128*. The value *None* indicates the size cannot be + reliably determined by python-oracledb, which occurs when using Thick mode + with Oracle Client libraries 12.1 (or older) to connect to Oracle Database + 12.2, or later. - .. deprecated:: cx_Oracle 8.2 + .. versionadded:: 2.5.0 - .. note:: +.. attribute:: Connection.max_open_cursors - This attribute is an extension to the DB API definition. + 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'``. When + using python-oracledb Thick mode, Oracle Client libraries 12.1 (or later) + are required. + .. dbapiattributeextension:: + + .. versionadded:: 2.0.0 .. attribute:: Connection.module - This write-only attribute sets the module column in the v$session table. + 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``. + + .. 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 + default behavior will take place for all columns fetched from cursors. - .. note: + See :ref:`outputtypehandlers`. - This attribute is an extension to the DB API definition. + .. versionchanged:: 1.4 -.. attribute:: Connection.nencoding + 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. - This read-only attribute returns the IANA character set name of the - national character set in use by the Oracle client. This is always the value "UTF-8". + .. dbapiattributeextension:: - .. deprecated:: cx_Oracle 8.2 +.. attribute:: Connection.proxy_user - .. note:: + This read-only attribute returns the name of the user which was used as a + proxy when creating the connection to the database. - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: -.. attribute:: Connection.outputtypehandler + .. versionadded:: 2.0.0 - 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, name, defaultType, length, precision, - scale) 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 columns fetched from - cursors. +.. attribute:: Connection.sdu - See :ref:`outputtypehandlers`. + This read-only attribute specifies the size of the Session Data Unit (SDU) + that is being used by the connection. The value will be the lesser of the + requested python-oracledb size and the maximum size allowed by the database + network configuration. It is available only in the python-oracledb Thin + mode. - .. note:: + .. dbapiattributeextension:: + + .. versionadded:: 2.0.0 + +.. attribute:: Connection.serial_num + + This read-only attribute specifies the session serial number associated + with the connection. It is the same value returned by the SQL + ``SELECT SERIAL# FROM V$SESSION WHERE SID=SYS_CONTEXT('USERENV', 'SID')``. + It is available only in python-oracledb Thin mode. + + + 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. + + .. dbapiattributeextension:: + + .. versionadded:: 2.5.0 + +.. attribute:: Connection.service_name + + This read-only attribute specifies the Oracle Database service name + associated with the connection. This is the same value returned by the SQL + ``SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL``. + + .. dbapiattributeextension:: + + .. versionadded:: 2.0.0 + +.. attribute:: Connection.session_id + + This read-only attribute specifies the session identifier associated with + the connection. It is the same value returned by the SQL + ``SELECT SYS_CONTEXT('USERENV', 'SID') FROM DUAL``. It is available + only in python-oracledb Thin mode. + + 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:: + + .. versionadded:: 2.5.0 .. attribute:: Connection.stmtcachesize @@ -764,73 +913,90 @@ 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). + 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*). - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.tnsentry - - This read-only attribute returns the TNS entry of the database to which a - connection has been established. + .. dbapiattributeextension:: - .. deprecated:: cx_Oracle 8.2 +.. attribute:: Connection.transaction_in_progress - Use the attribute :attr:`~Connection.dsn` instead. + This read-only attribute specifies whether a transaction is currently in + progress on the database associated with the connection. - .. 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. + .. dbapiattributeextension:: + .. note:: - This attribute is an extension to the DB API definition. + 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). - .. note:: +.. attribute:: Connection.warning + + This read-only attribute provides an :ref:`oracledb._Error` + object giving information about any database warnings (such as the password + being in the grace period, or the pool being created with a smaller than + requested size due to database resource restrictions) that were generated + during connection establishment or by :meth:`oracledb.create_pool()`. The + attribute will be present if there was a warning, but creation otherwise + completed successfully. The connection will be usable despite the warning. + + For :ref:`standalone connections `, + ``Connection.warning`` will be present for the lifetime of the connection. + + For :ref:`pooled connections `, ``Connection.warning`` will be + cleared when a connection is released to the pool such as with + :meth:`ConnectionPool.release()`. + + In python-oracledb Thick mode, warnings may be generated during pool + creation itself. These warnings will be placed on new connections created + by the pool, provided no warnings were generated by the individual + connection creations, in which case those connection warnings will be + returned. + + If no warning was generated the value *None* is returned. + + .. dbapiattributeextension:: - If you connect to Oracle Database 18 or higher with client libraries - 12.2 or lower that you will only receive the base version (such as - 18.0.0.0.0) instead of the full version (18.3.0.0.0). + .. versionadded:: 2.0.0 diff --git a/doc/src/api_manual/connection_pool.rst b/doc/src/api_manual/connection_pool.rst index f60a0f3e..2de1ad9b 100644 --- a/doc/src/api_manual/connection_pool.rst +++ b/doc/src/api_manual/connection_pool.rst @@ -4,24 +4,21 @@ 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 -`Oracle Call Interface (OCI) session pool -`__. This +`Oracle Call Interface (OCI) session pool `__. This implementation is only used in the python-oracledb Thick mode and is not -available in the python-oracledb Thin mode). +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 @@ -41,6 +38,8 @@ The function :meth:`oracledb.SessionPool` that is used to create pools is deprecated in python-oracledb 1.0 and has been deprecated by the function :meth:`oracledb.create_pool`. +.. _connpoolmethods: + ConnectionPool Methods ====================== @@ -56,16 +55,16 @@ ConnectionPool Methods be raised. The ``cclass`` parameter, if specified, should be a string corresponding to - the connection class for Database Resident Connection Pooling (DRCP). + the connection class for :ref:`drcp`. The ``purity`` parameter is expected to be one of - :data:`~oracledb.PURITY_NEW`, :data:`~oracledb.PURITY_ANY`, or + :data:`~oracledb.PURITY_NEW`, :data:`~oracledb.PURITY_SELF`, or :data:`~oracledb.PURITY_DEFAULT`. The ``tag`` parameter, if specified, is expected to be a string with name=value pairs like "k1=v1;k2=v2" and will limit the connections that can be returned from a connection pool unless the ``matchanytag`` parameter is - set to True. In that case, connections with the specified tag will be + 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 @@ -74,9 +73,12 @@ 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. + 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 + calling ``pool.acquire()``. .. method:: ConnectionPool.close(force=False) @@ -84,15 +86,13 @@ 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) Drops the connection from the pool which is useful if the connection is no longer usable (such as when the session is killed). - .. method:: ConnectionPool.reconfigure([min, max, increment, getmode, \ timeout, wait_timeout, max_lifetime_session, max_sessions_per_shard, \ soda_metadata_cache, stmtcachesize, ping_interval]) @@ -145,7 +145,6 @@ ConnectionPool Methods See :ref:`Connection Pool Reconfiguration `. - .. method:: ConnectionPool.release(connection, tag=None) Releases the connection back to the pool now, rather than whenever __del__ @@ -162,12 +161,13 @@ 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: ConnectionPool Attributes ========================= @@ -177,13 +177,11 @@ ConnectionPool Attributes This read-only attribute returns the number of connections currently acquired. - .. attribute:: ConnectionPool.dsn This read-only attribute returns the TNS entry of the database to which a connection has been established. - .. attribute:: ConnectionPool.getmode This read-write attribute determines how connections are returned from the @@ -199,34 +197,35 @@ ConnectionPool Attributes .. attribute:: ConnectionPool.homogeneous - This read-write boolean attribute indicates whether the pool is considered + This read-only boolean attribute indicates whether the pool is considered :ref:`homogeneous ` or not. If the pool is not homogeneous, different authentication can be used for each connection acquired from the pool. - .. attribute:: ConnectionPool.increment This read-only attribute returns the number of connections that will be established when additional connections need to be created. - .. attribute:: ConnectionPool.max This read-only attribute returns the maximum number of connections that the pool can control. - .. 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. + 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 @@ -234,29 +233,25 @@ 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. - .. attribute:: ConnectionPool.min This read-only attribute returns the number of connections with which the connection pool was created and the minimum number of connections that will be controlled by the connection pool. - .. attribute:: ConnectionPool.name This read-only attribute returns the name assigned to the pool by Oracle. - .. attribute:: ConnectionPool.opened This read-only attribute returns the number of connections currently opened by the pool. - .. attribute:: ConnectionPool.ping_interval This read-write integer attribute specifies the pool ping interval in @@ -266,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. @@ -286,43 +281,32 @@ 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. -.. attribute:: ConnectionPool.tnsentry - - This read-only attribute returns the TNS entry of the database to which a - connection has been established. - - .. deprecated:: cx_Oracle 8.2 - - Use the attribute :attr:`~ConnectionPool.dsn` instead. - .. attribute:: ConnectionPool.username This read-only attribute returns the name of the user which established the connection to the database. - .. attribute:: ConnectionPool.wait_timeout This read-write attribute specifies the time (in milliseconds) that the diff --git a/doc/src/api_manual/cursor.rst b/doc/src/api_manual/cursor.rst index 55b4cccd..3ebf2782 100644 --- a/doc/src/api_manual/cursor.rst +++ b/doc/src/api_manual/cursor.rst @@ -4,7 +4,7 @@ API: Cursor Objects ******************* -A cursor object can be created with :meth:`Connection.cursor`. +A cursor object can be created with :meth:`Connection.cursor()`. Cursor Methods ============== @@ -13,24 +13,24 @@ 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:: + .. dbapimethodextension:: + +.. method:: Cursor.__iter__() - This method is an extension to the DB API definition. + Returns the cursor itself to be used as an iterator. + .. dbapimethodextension:: It is mentioned in PEP 249 as an optional extension. .. method:: Cursor.arrayvar(typ, value, [size]) Creates an array variable associated with the cursor of the given type and - size and return a :ref:`variable object `. The value is either an + size and returns a :ref:`variable object `. The value is either an integer specifying the number of elements to allocate or it is a list and the number of elements allocated is drawn from the size of the list. If the value is a list, the variable is also set with the contents of the list. If @@ -45,63 +45,71 @@ 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, returnType, parameters=[], \ +.. method:: Cursor.callfunc(name, return_type, parameters=[], \ keyword_parameters={}) - Calls a function with the given name. The return type is specified in the - same notation as is required by :meth:`~Cursor.setinputsizes()`. The - sequence of parameters must contain one entry for each parameter that the - function expects. Any keyword parameters will be included after the - positional parameters. The result of the call is the return value of the - function. + Calls a PL/SQL function with the given name and returns its value. - See :ref:`plsqlfunc` for an example. + The ``return_type`` parameter for :meth:`~Cursor.callfunc()` is expected to + be a Python type, one of the :ref:`oracledb types ` or an + :ref:`Object Type `. - For consistency and compliance with the PEP 8 naming style, the - parameter `keywordParameters` was renamed to `keyword_parameters`. The - old name will continue to work as a keyword parameter for a period of - time. + The sequence of parameters must contain one entry for each parameter that + the PL/SQL function expects. Any keyword parameters will be included after + the positional parameters. - .. note:: + Use :meth:`Cursor.var()` to define any OUT or IN OUT parameters, if + necessary. - The DB API definition does not define this method. + See :ref:`plsqlfunc` for examples. - .. note:: + For consistency and compliance with the PEP 8 naming style, the parameter + ``keywordParameters`` was renamed to ``keyword_parameters``. The old name + will continue to work for a period of time. - If you intend to call :meth:`Cursor.setinputsizes()` on the cursor - prior to making this call, then note that the first item in the - parameter list refers to the return value of the function. + .. dbapimethodextension:: + .. note:: + + In line with the Python DB API, it is not recommended to call + :meth:`Cursor.setinputsizes()` prior to calling + :meth:`~Cursor.callfunc()`. Use :meth:`Cursor.var()` instead. In + existing code that calls :meth:`~Cursor.setinputsizes()`, the first + item in the :meth:`~Cursor.setinputsizes()` parameter list refers to + the return value of the PL/SQL function. .. method:: Cursor.callproc(name, parameters=[], keyword_parameters={}) - Calls a procedure with the given name. The sequence of parameters must - contain one entry for each parameter that the procedure expects. The result - of the call is a modified copy of the input sequence. Input parameters are - left untouched; output and input/output parameters are replaced with - possibly new values. Keyword parameters will be included after the - positional parameters and are not returned as part of the output sequence. + Calls a PL/SQL procedure with the given name. + + The sequence of parameters must contain one entry for each parameter that + the procedure expects. The result of the call is a modified copy of the + input sequence. Input parameters are left untouched; output and + input/output parameters are replaced with possibly new values. Keyword + parameters will be included after the positional parameters and are not + returned as part of the output sequence. + + Use :meth:`Cursor.var()` to define any OUT or IN OUT parameters if + necessary. + + No query result set is returned by :meth:`~Cursor.callproc()`. Instead, use + :ref:`REF CURSOR ` parameters or :ref:`Implicit Results + `. See :ref:`plsqlproc` for an example. - For consistency and compliance with the PEP 8 naming style, the - parameter `keywordParameters` was renamed to `keyword_parameters`. The - old name will continue to work as a keyword parameter for a period of - time. + For consistency and compliance with the PEP 8 naming style, the parameter + ``keywordParameters`` was renamed to ``keyword_parameters``. The old name + will continue to work for a period of time. .. note:: @@ -130,66 +138,69 @@ 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 that are not passed in during subsequent executions will retain the value passed in during the last execution that contained them. - For maximum efficiency when reusing an 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 + For maximum efficiency when reusing a statement, it is best to use the + :meth:`Cursor.setinputsizes()` method to specify the parameter types and + sizes ahead of time; in particular, *None* is assumed to be a string of length 1 so any values that are later bound as numbers or dates will raise a TypeError exception. 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:: The DB API definition does not define the return value of this method. - .. method:: Cursor.executemany(statement, parameters, batcherrors=False, \ arraydmlrowcounts=False) - Prepares a statement for execution against a database and then execute it - against all parameter mappings or sequences found in the sequence - parameters. See :ref:`batchstmnt`. + Executes a SQL statement once using all bind value mappings or sequences + found in the sequence parameters. This can be used to insert, update, or + delete multiple rows in a table with a single python-oracledb call. It can + also invoke a PL/SQL procedure multiple times. See :ref:`batchstmnt`. The ``statement`` parameter is managed in the same way as the - :meth:`~Cursor.execute()` method manages it. 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", where varies with the - size of each element being allocated in the buffer. If you receive this - error, decrease the number of elements in the sequence parameters. + :meth:`Cursor.execute()` method manages it. + + The ``parameters`` parameter can be a list of tuples, where each tuple item + maps to one bind variable placeholder in ``statement``. It can also be a + list of dictionaries, where the keys match the bind variable placeholder + names in ``statement``. If there are no bind values, or values have + previously been bound, the ``parameters`` value can be an integer + specifying the number of iterations. - If there are no parameters, or parameters have previously been bound, the - number of iterations can be specified as an integer instead of needing to - provide a list of empty mappings or sequences. + In python-oracledb Thick mode, if the size of the buffers allocated for any + of the parameters exceeds 2 GB, you will receive the error ``DPI-1015: + array size of is too large``. If you receive this error, decrease the + number of rows being inserted. - When True, the ``batcherrors`` parameter enables batch error support within - Oracle and ensures that the call succeeds even if an exception takes place - in one or more of the sequence of parameters. The errors can then be - retrieved using :meth:`~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 - then be retrieved using :meth:`~Cursor.getarraydmlrowcounts()`. + 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 parameter types and - sizes ahead of time; in particular, None is assumed to be a string of - length 1 so any values that are later bound as numbers or dates will raise - a TypeError exception. - + :meth:`Cursor.setinputsizes()` method to specify the bind value types and + sizes. In particular, if the type is not explicitly specified, the value + *None* is assumed to be a string of length 1 so any values that are later + bound as numbers or dates will raise a TypeError exception. .. method:: Cursor.fetchall() @@ -199,12 +210,11 @@ Cursor Methods operation, as internally reads from the database are done in batches corresponding to the arraysize. - An exception is raised if the previous call to :meth:`~Cursor.execute()` + An exception is raised if the previous call to :meth:`Cursor.execute()` did not produce any result set or no call was issued yet. See :ref:`fetching` for an example. - .. method:: Cursor.fetchmany(size=cursor.arraysize) Fetches the next set of rows of a query result, returning a list of tuples. @@ -212,50 +222,44 @@ 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()` + An exception is raised if the previous call to :meth:`Cursor.execute()` did not produce any result set or no call was issued yet. See :ref:`fetching` for an example. .. method:: Cursor.fetchone() - Fetches the next row of a query result set, returning a single tuple or None - when no more data is available. + 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()` + An exception is raised if the previous call to :meth:`Cursor.execute()` did not produce any result set or no call was issued yet. See :ref:`fetching` for an example. - .. method:: Cursor.getarraydmlrowcounts() - Retrieves the DML row counts after a call to :meth:`~Cursor.executemany()` - with arraydmlrowcounts enabled. This will return a list of integers + Retrieves the DML row counts after a call to :meth:`Cursor.executemany()` + with ``arraydmlrowcounts`` enabled. This will return a list of integers corresponding to the number of rows affected by the DML statement for each - element of the array passed to :meth:`~Cursor.executemany()`. + element of the array passed to :meth:`Cursor.executemany()`. - .. note:: - - The DB API definition does not define this method and it is only - available for Oracle 12.1 and higher. + This method is only available for Oracle Database 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() @@ -263,120 +267,121 @@ Cursor Methods available from a PL/SQL block or procedure without the use of OUT ref cursor parameters. The PL/SQL block or procedure opens the cursors and marks them for return to the client using the procedure - dbms_sql.return_result. Cursors returned in this fashion should not be - closed. They will be closed automatically by the parent cursor when it is - closed. Closing the parent cursor will invalidate the cursors returned by - this method. + dbms_sql.return_result. In python-oracledb Thick mode, closing the parent + cursor will result in the automatic closure of the implicit result set + cursors. See :ref:`implicitresults`. - .. note:: + This method is only available for Oracle Database 12.1 (or later). For + python-oracledb :ref:`Thick ` mode, Oracle Client 12.1 (or + later) is additionally required. - The DB API definition does not define this method and it is only - available for Oracle Database 12.1 (both client and server must be at - this level or higher). 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.__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 most like the DB API method nextset(), but unlike that method + (which requires that the next result set overwrite the current result + set), this method returns cursors which can be fetched independently of + each other. .. method:: Cursor.parse(statement) - This can be used to parse a statement without actually executing it (this - step is done automatically by Oracle when a statement is executed). + This can be used to parse a statement without actually executing it + (parsing step is done automatically by Oracle when a statement is + :meth:`executed `). - .. note:: - - The DB API definition does not define this method. + .. dbapimethodextension:: .. note:: You can parse any DML or DDL statement. DDL statements are executed - immediately and an implied commit takes place. - + immediately and an implied commit takes place. You can also parse + PL/SQL statements. .. method:: Cursor.prepare(statement, tag, cache_statement=True) - This can be used before a call to :meth:`~Cursor.execute()` 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()` is made with - None or the same string object as the statement. + This can be used before a call to :meth:`Cursor.execute()` or + :meth:`Cursor.executemany()` to define the statement that will be + executed. When this is done, the prepare phase will not be performed when + the call to :meth:`Cursor.execute()` or :meth:`Cursor.executemany()` is + made with *None* or the same string object as the statement. If the ``tag`` parameter is specified and the ``cache_statement`` parameter - is True, the statement will be returned to the statement cache with the + 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:: + .. dbapimethodextension:: It is mentioned in PEP 249 as an optional extension. + +.. method:: Cursor.setinputsizes(*args, **keywordArgs) - This method is an extension to the DB API definition but it is - mentioned in PEP 249 as an optional extension. + This can be used before calls to :meth:`Cursor.execute()` or + :meth:`Cursor.executemany()` to predefine memory areas used for + :ref:`bind variables `. Each parameter should be a type object + corresponding to the data that will be used for a bind variable placeholder + in the SQL or PL/SQL statement. Alternatively, it can be an integer + specifying the maximum length of a string bind variable value. + Use keyword parameters when :ref:`binding by name `. Use + positional parameters when :ref:`binding by position `. The + parameter value can be *None* to indicate that python-oracledb should + determine the required space from the data value provided. -.. method:: Cursor.setinputsizes(\*args, \*\*keywordArgs) + The parameters or keyword names correspond to the bind variable + placeholders used in the SQL or PL/SQL statement. Note this means that for + use with :meth:`Cursor.executemany()` it does not correspond to the number + of bind value mappings or sequences being passed. - This can be used before a call to :meth:`~Cursor.execute()`, - :meth:`~Cursor.callfunc()` or :meth:`~Cursor.callproc()` to predefine - memory areas for the operation's parameters. Each parameter should be a - type object corresponding to the input that will be used or it should be an - integer specifying the maximum length of a string parameter. Use keyword - parameters when binding by name and positional parameters when binding by - position. The singleton None can be used as a parameter when using - positional parameters to indicate that no space should be reserved for that - position. + When repeated calls to :meth:`Cursor.execute()` or + :meth:`Cursor.executemany()` are made binding different string data + lengths, using :meth:`~Cursor.setinputsizes()` can help reduce the + database's SQL "version count" for the statement. See :ref:`Reducing the + SQL Version Count `. .. note:: - If you plan to use :meth:`~Cursor.callfunc()` then be aware that the - first parameter in the list refers to the return value of the function. + :meth:`Cursor.setinputsizes()` should not be used for bind variables + passed to :meth:`Cursor.callfunc()` or + :meth:`Cursor.callproc()`. Instead, use :meth:`Cursor.var()`. + If :meth:`Cursor.setinputsizes()` is used with + :meth:`Cursor.callfunc()`, the first parameter in the list refers to + the return value of the PL/SQL function. .. method:: Cursor.setoutputsize(size, [column]) This method does nothing and is retained solely for compatibility with the - DB API. The module automatically allocates as much space as needed to fetch - LONG and LONG RAW columns (or CLOB as string and BLOB as bytes). - + DB API. Python-oracledb automatically allocates as much space as needed to + fetch LONG and LONG RAW columns, and also to fetch CLOB as string and BLOB + as bytes. .. method:: Cursor.var(typ, [size, arraysize, inconverter, outconverter, \ - typename, encoding_errors, bypass_decode]) + typename, encoding_errors, bypass_decode, convert_nulls]) - Creates a variable with the specified characteristics. This method was - designed for use with PL/SQL in/out variables where the length or type - cannot be determined automatically from the Python object passed in or for - use in input and output type handlers defined on cursors or connections. + Creates a :ref:`variable object ` with the specified + characteristics. This method can be used for binding to PL/SQL IN and OUT + parameters where the length or type cannot be determined automatically from + the Python variable being bound. It can also be used in :ref:`input + ` and :ref:`output ` type handlers. The ``typ`` parameter specifies the type of data that should be stored in the variable. This should be one of the :ref:`database type constants @@ -413,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. @@ -435,20 +440,28 @@ 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. - For consistency and compliance with the PEP 8 naming style, the - parameter `encodingErrors` was renamed to `encoding_errors`. The old - name will continue to work as a keyword parameter for a period of time. + The ``convert_nulls`` parameter, if specified, should be passed as a boolean + value. Passing the value *True* causes the ``outconverter`` to be called + when a null value is fetched from the database; otherwise, the + ``outconverter`` is only called when non-null values are fetched from the + database. - .. note:: + For consistency and compliance with the PEP 8 naming style, the parameter + ``encodingErrors`` was renamed to ``encoding_errors``. The old name will + continue to work as a keyword parameter for a period of time. + + .. versionchanged:: 1.4.0 - The DB API definition does not define this method. + The ``convert_nulls`` parameter was added. + + .. dbapimethodextension:: Cursor Attributes ================= @@ -460,50 +473,48 @@ Cursor Attributes from SELECT statements and REF CURSORS. The value can drastically affect the performance of a query since it directly affects the number of network round trips between Python and the database. For methods like - :meth:`~Cursor.fetchone()` and :meth:`~Cursor.fetchall()` it does not change + :meth:`Cursor.fetchone()` and :meth:`Cursor.fetchall()` it does not change how many rows are returned to the application. For - :meth:`~Cursor.fetchmany()` it is the default number of rows to fetch. + :meth:`Cursor.fetchmany()` it is the default number of rows to fetch. The attribute is only used for tuning row and SODA document fetches from the database. It does not affect data inserts. - Due to the performance benefits, the default ``Cursor.arraysize`` is 100 - instead of the 1 that the Python DB API recommends. + 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. .. attribute:: Cursor.bindvars This read-only attribute provides the bind variables used for the last - execute. The value will be either a list or a dictionary depending on - whether binding was done by position or name. Care should be taken when - referencing this attribute. In particular, elements should not be removed - or replaced. - - .. note:: + statement that was executed on the cursor. The value will be either a list + or a dictionary, depending on whether binding was done by position or + name. Care should be taken when referencing this attribute. In particular, + elements should not be removed or replaced. - 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:: + .. dbapimethodextension:: It is mentioned in PEP 249 as an optional extension. - This attribute is an extension to the DB API definition but it is - mentioned in PEP 249 as an optional extension. +.. attribute:: Cursor.description -.. data:: 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 + WITH statements, or if the cursor has not had :meth:`Cursor.execute()` + invoked yet. - This read-only attribute is a sequence of 7-item sequences. Each of these - sequences contains information describing one result column: (name, type, - display_size, internal_size, precision, scale, null_ok). 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:`~Cursor.execute()` method yet. + .. versionchanged:: 1.4.0 - The type will be one of the :ref:`database type constants ` - defined at the module level. + Previously, this attribute was a sequence of 7-tuples. Each of these + tuples contained information describing one query column: "(name, type, + display_size, internal_size, precision, scale, null_ok)". .. attribute:: Cursor.fetchvars @@ -512,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 @@ -522,61 +531,65 @@ 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. - .. note:: + See :ref:`inputtypehandlers`. - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: -.. data:: Cursor.lastrowid +.. attribute:: Cursor.lastrowid This read-only attribute returns the rowid of the last row modified by the cursor. If no row was modified by the last operation performed on the - cursor, the value None is returned. - + 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, name, defaultType, length, precision, scale) 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, then the default + handler(cursor, metadata) and the return value is expected to be a + :ref:`variable object ` or *None* in which case a default variable + object will be created. If this attribute is *None*, then the default behavior will take place for all columns fetched from this cursor. See :ref:`outputtypehandlers`. - .. note:: + .. dbapiattributeextension:: - This attribute is an extension to the DB API definition. + .. 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. .. 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. - See :ref:`Tuning Fetch Performance ` for more information. + Queries that return LOBs and similar types will never prefetch rows, so the + ``prefetchrows`` value is ignored in those cases. - .. note:: + See :ref:`Tuning Fetch Performance ` for more information. - 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), that have been - affected by the operation (for insert, update, delete and merge - statements), or the number of successful executions of the statement - (for PL/SQL statements). - + been fetched from the cursor (for select statements) or that have been + affected by the operation (for insert, update, delete, and merge + statements). For all other statements the value is always *0*. If the + cursor or connection is closed, the value returned is *-1*. .. attribute:: Cursor.rowfactory @@ -588,9 +601,7 @@ Cursor Attributes See :ref:`rowfactories`. - .. note:: - - The DB API definition does not define this attribute. + .. dbapiattributeextension:: .. attribute:: Cursor.scrollable @@ -598,18 +609,30 @@ Cursor Attributes scrolled or not. By default, cursors are not scrollable, as the server resources and response times are greater than nonscrollable cursors. This attribute is checked and the corresponding mode set in Oracle when calling - the method :meth:`~Cursor.execute()`. + the method :meth:`Cursor.execute()`. - .. note:: - - The DB API definition does not define this attribute. + .. dbapiattributeextension:: .. attribute:: Cursor.statement This read-only attribute provides the string object that was previously - prepared with :meth:`~Cursor.prepare()` or executed with - :meth:`~Cursor.execute()`. + prepared with :meth:`Cursor.prepare()` or executed with + :meth:`Cursor.execute()`. - .. note:: + .. dbapiattributeextension:: + +.. attribute:: Cursor.warning + + This read-only attribute provides an :ref:`oracledb._Error` + object giving information about any database warnings (such as PL/SQL + compilation warnings) that were generated during the last call to + :meth:`Cursor.execute()` or :meth:`Cursor.executemany()`. This value is + automatically cleared on the next call to :meth:`Cursor.execute()` or + :meth:`Cursor.executemany()`. If no warning was generated the value + *None* is returned. + + See :ref:`plsqlwarning` for more information. + + .. 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 3cc09af2..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 ==================== @@ -35,6 +35,15 @@ DbObjectType Attributes ` that make up the object type. +.. 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 + another object type; otherwise, it will be one of the + :ref:`database type constants `. + + .. attribute:: DbObjectType.iscollection This read-only attribute returns a boolean indicating if the object type @@ -46,13 +55,10 @@ DbObjectType Attributes This read-only attribute returns the name of the type. -.. attribute:: DbObjectType.element_type +.. attribute:: DbObjectType.package_name - This read-only attribute returns the type of elements found in collections - of this type, if :attr:`~DbObjectType.iscollection` is True; otherwise, - it returns None. If the collection contains objects, this will be - another object type; otherwise, it will be one of the - :ref:`database type constants `. + 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*). .. attribute:: DbObjectType.schema @@ -64,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 ++++++++++++++++ @@ -109,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) @@ -123,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) @@ -135,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) @@ -180,10 +185,20 @@ DbObject Attributes DbObjectAttribute Objects ========================= -.. note:: +The elements of :attr:`DbObjectType.attributes` are instances of this type. - This object is an extension to the DB API. The elements of - :attr:`DbObjectType.attributes` are instances of this type. +.. dbapiobjectextension:: + +.. attribute:: DbObjectAttribute.max_size + + This read-only attribute returns the maximum size (in bytes) of the + attribute when the attribute's type is one of + :data:`oracledb.DB_TYPE_CHAR`, :data:`oracledb.DB_TYPE_NCHAR`, + :data:`oracledb.DB_TYPE_NVARCHAR`, :data:`oracledb.DB_TYPE_RAW`, or + :data:`oracledb.DB_TYPE_VARCHAR`. For all other types the value returned is + *None*. + + .. versionadded:: 3.0.0 .. attribute:: DbObjectAttribute.name @@ -191,6 +206,24 @@ DbObjectAttribute Objects This read-only attribute returns the name of the attribute. +.. attribute:: DbObjectAttribute.precision + + This read-only attribute returns the precision of the attribute when the + attribute's type is :data:`oracledb.DB_TYPE_NUMBER`. For all other types + the value returned is *None*. + + .. versionadded:: 3.0.0 + + +.. attribute:: DbObjectAttribute.scale + + This read-only attribute returns the scale of the attribute when the + attribute's type is :data:`oracledb.DB_TYPE_NUMBER`. For all other types + the value returned is *None*. + + .. versionadded:: 3.0.0 + + .. attribute:: DbObjectAttribute.type This read-only attribute returns the type of the attribute. This will be an diff --git a/doc/src/api_manual/defaults.rst b/doc/src/api_manual/defaults.rst index ef33020e..4174e881 100644 --- a/doc/src/api_manual/defaults.rst +++ b/doc/src/api_manual/defaults.rst @@ -25,57 +25,141 @@ 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 + python-oracledb Thick and Thin mode. + + In python-oracledb Thick mode, this attribute is used if the + ``driver_name`` parameter is not specified in + :meth:`oracledb.init_oracle_client()`. In Thin mode, this attribute is + used if the ``driver_name`` parameter is not specified in + :meth:`oracledb.connect()`, :meth:`oracledb.connect_async()`, + :meth:`oracledb.create_pool()`, or :meth:`oracledb.create_pool_async()`. + If the value of this attribute is *None*, the value set when connecting in + python-oracledb Thick mode is like "python-oracledb thk : " and + in Thin mode is like "python-oracledb thn : ". See + :ref:`otherinit`. + + .. versionadded:: 2.5.0 + .. attribute:: defaults.fetch_decimals - Identifies whether numbers should be fetched as ``decimal.Decimal`` values. + Identifies whether numbers should be fetched as `decimal.Decimal + `__ values. This can help avoid issues with converting numbers from Oracle Database's decimal format to Python's binary format. - An output type handler such as previously required in cx_Oracle (see - `return_numbers_as_decimals.py `__) can alternatively be - used to adjust the returned type. If a type handler exists and returns a - variable (that is, `cursor.var(...)`), then that return variable is used. - If the type handler returns None, then the value of + 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 strings or bytes - are fetched. 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 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*. + +.. attribute:: defaults.machine + + The default value that represents the machine name of the client + connecting to Oracle Database. This is the value used in the + MACHINE column of the V$SESSION view. + + This attribute takes the host name where the application is running as its + initial value. + + This attribute is only used in python-oracledb Thin mode. + + .. versionadded:: 2.5.0 + +.. attribute:: defaults.osuser + + The default value that represents the operating system user that initiates + the database connection. This is the value used in the OSUSER + column of the V$SESSION view. - 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. + This attribute takes the login name of the user as its initial value. - This attribute has an initial value of True. + This attribute is only used in python-oracledb Thin mode. + + .. versionadded:: 2.5.0 .. attribute:: defaults.prefetchrows The default value for :attr:`Cursor.prefetchrows`. This is a query tuning attribute, see :ref:`Tuning Fetch Performance `. - This attribute 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 + + The default value that represents the program name connected to the + database. This is the value used in the PROGRAM column of the + V$SESSION view. + + This attribute has an initial value that is populated by `sys.executable + `__. + + This attribute is only used in python-oracledb Thin mode. + + .. versionadded:: 2.5.0 .. attribute:: defaults.stmtcachesize @@ -83,4 +167,65 @@ 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 + + The default value that represents the terminal identifier from which the + connection originates. This is the value used in the TERMINAL + column of the V$SESSION view. + + 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 93cce894..92bb3dc3 100644 --- a/doc/src/api_manual/deprecations.rst +++ b/doc/src/api_manual/deprecations.rst @@ -1,277 +1,358 @@ .. _deprecations: -************ -Deprecations -************ +*********************************** +Deprecated and Desupported Features +*********************************** -The following tables contain all of the deprecations in the python-oracledb API, -when they were first deprecated and a comment on what should be used instead, -if applicable. The most recent deprecations are listed first. +The following tables contain the deprecated and desupported features of the +python-oracledb API, and the replacement to be used instead, if applicable. +The desupported API feature is a previous deprecation that has been removed +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. 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 + :class: wy-table-responsive + :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecation and the replacement to use, if applicable. + :name: _deprecations_3_0 + + * - Name + - Comments + * - Parameter ``pool`` of :meth:`oracledb.connect()` and :meth:`oracledb.connect_async()` + - 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 + :class: wy-table-responsive + :summary: The first column, Name, displays the desupported feature. The second column, Comments, includes information about the desupport and the replacement to use, if applicable. + :name: _desupported_2_0 + + * - Name + - Comments + * - ``oracledb.__future__.old_json_col_as_obj`` + - VARCHAR2 and LOB columns created with the ``IS JSON`` check constraint + are now always fetched as JSON. Use an :ref:`output type handler + ` if the old behavior is required. + * - Parameters ``encoding`` and ``nencoding`` of :func:`oracledb.connect()` + and :func:`oracledb.create_pool()`, and the related attributes on the + objects created + - The driver encodings are always UTF-8. Remove uses of ``encoding`` and + ``nencoding`` from your code. + * - Parameter ``threaded`` of :func:`oracledb.connect()` and + :func:`oracledb.create_pool()` + - Threading is always used. Remove uses of ``threaded`` from your code. + * - Parameter ``waitTimeout`` of :func:`oracledb.create_pool()` and + ``oracledb.SessionPool()`` + - Replace with parameter ``wait_timeout`` + * - Parameter ``maxLifetimeSession`` of :func:`oracledb.create_pool()` and + ``oracledb.SessionPool()`` + - Replace with parameter ``max_lifetime_session`` + * - Parameter ``sessionCallback`` of :func:`oracledb.create_pool()` and + ``oracledb.SessionPool()`` + - Replace with parameter ``session_callback`` + * - Parameter ``maxSessionsPerShard`` of :func:`oracledb.create_pool()` and + ``oracledb.SessionPool()`` + - Replace with parameter ``max_sessions_per_shard`` + * - Attribute ``maxBytesPerCharacter`` of the :ref:`Connection object + ` + - The driver encodings are always UTF-8 so this attribute can be replaced by + the constant value 4 + * - ``Connection.tnsentry`` + - Replace with :attr:`Connection.dsn` + * - ``SessionPool.tnsentry`` + - Replace with :attr:`ConnectionPool.dsn` + +.. list-table-with-summary:: Deprecated in python-oracledb 2.0 + :header-rows: 1 + :class: wy-table-responsive + :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecation and the replacement to use, if applicable. + :name: _deprecations_2_0 + + * - Name + - Comments + * - Calling :meth:`Variable.setvalue()` with a string value when the + variable type is one of :data:`oracledb.DB_TYPE_BLOB`, + :data:`oracledb.DB_TYPE_CLOB` or :data:`oracledb.DB_TYPE_NCLOB`. + - Call :meth:`Connection.createlob()` with the value instead and pass the + result to :meth:`Variable.setvalue()`. + * - Setting an attribute of type :data:`oracledb.DB_TYPE_BLOB`, + :data:`oracledb.DB_TYPE_CLOB` or :data:`oracledb.DB_TYPE_NCLOB` on a + database object to a string value. + - Call :meth:`Connection.createlob()` with the value instead and set the + attribute with the result. + +.. list-table-with-summary:: Deprecated in python-oracledb 1.4 + :header-rows: 1 + :class: wy-table-responsive + :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecation and the replacement to use, if applicable. + :name: _deprecations_1_4 + + * - Name + - Comments + * - Output type handler with arguments + ``handler(cursor, name, default_type, length, precision, scale)`` + - Replace with ``handler(cursor, metadata)``. See + :ref:`outputtypehandlers`. .. list-table-with-summary:: Deprecated in python-oracledb 1.0 :header-rows: 1 :class: wy-table-responsive - :summary: The first column, Name, displays the deprecated API name. The second column, Comments, includes information about when the API was deprecated and what API to use, if applicable. + :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecation and the replacement to use, if applicable. :name: _deprecations_1 * - Name - Comments - * - `SessionPool class `_ and use of `cx_Oracle.SessionPool() `_. + * - SessionPool class and use of ``cx_Oracle.SessionPool()`` - Replace by the equivalent :ref:`ConnectionPool Class `. Use the new method :meth:`oracledb.create_pool()` to create connection pools. * - :meth:`Connection.begin()` - - Replace by the new :ref:`tcp` functionality. + - Replace by the new :ref:`Two-Phase Commits (TPC) ` functionality. * - :meth:`Connection.prepare()` - - Replace by the new :ref:`tcp` functionality. + - Replace by the new :ref:`Two-Phase Commits (TPC) ` functionality. * - Parameters ``encoding`` and ``nencoding`` of the :func:`oracledb.connect()`, :func:`oracledb.create_pool()` and ``oracledb.SessionPool()`` methods - The encodings in use are always UTF-8. * - Parameter ``threaded`` of the :meth:`oracledb.connect()` method - - This was used to allow the Oracle Client libraries to support threaded applications. This value is ignored in python-oracledb because the threaded OCI is always enabled in the Thick mode, and the option is not relevant to the Thin mode. The equivalent parameter was already deprecated for `cx_Oracle.SessionPool() `_ in cx_Oracle 8.2. + - This was used to allow the Oracle Client libraries to support threaded applications. This value is ignored in python-oracledb because the threaded OCI is always enabled in the Thick mode, and the option is not relevant to the Thin mode. The equivalent parameter was already deprecated for ``cx_Oracle.SessionPool()`` in cx_Oracle 8.2. * - Attribute :attr:`Connection.maxBytesPerCharacter` of the Connection object - This was previously deprecated. In python-oracledb 1.0 it will return a constant value of 4 since encodings are always UTF-8. * - Size argument, ``numRows`` of the :meth:`Cursor.fetchmany()` method - Rename the parameter to ``size``. - * - `cx_Oracle.makedsn() `_ + * - ``cx_Oracle.makedsn()`` - Pass the connection string components as connection creation, or pool creation, parameters. Or use a :ref:`ConnectParams Class ` object. - * - oracledb.Connection() + * - ``oracledb.Connection()`` - This method is no longer recommended for creating connections. Use the equivalent function :meth:`oracledb.connect()` instead. * - Attribute ``Cursor.bindarraysize`` of the Cursor object - Remove this attribute since it is no longer needed. * - Constant :data:`~oracledb.ATTR_PURITY_DEFAULT` - - Replace by :data:`~oracledb.PURITY_DEFAULT`. + - Replace by :data:`oracledb.PURITY_DEFAULT`. * - Constant :data:`~oracledb.ATTR_PURITY_NEW` - - Replace by :data:`~oracledb.PURITY_NEW`. + - Replace by :data:`oracledb.PURITY_NEW`. * - Constant :data:`~oracledb.ATTR_PURITY_SELF` - - Replace by :data:`~oracledb.PURITY_SELF`. + - Replace by :data:`oracledb.PURITY_SELF`. * - Constant :data:`~oracledb.SPOOL_ATTRVAL_WAIT` - - Replace by :data:`~oracledb.POOL_GETMODE_WAIT`. + - Replace by :data:`oracledb.POOL_GETMODE_WAIT`. * - Constant :data:`~oracledb.SPOOL_ATTRVAL_NOWAIT` - - Replace by :data:`~oracledb.POOL_GETMODE_NOWAIT`. + - Replace by :data:`oracledb.POOL_GETMODE_NOWAIT`. * - Constant :data:`~oracledb.SPOOL_ATTRVAL_FORCEGET` - - Replace by :data:`~oracledb.POOL_GETMODE_FORCEGET`. + - Replace by :data:`oracledb.POOL_GETMODE_FORCEGET`. * - Constant :data:`~oracledb.SPOOL_ATTRVAL_TIMEDWAIT` - - Replace by :data:`~oracledb.POOL_GETMODE_TIMEDWAIT`. + - Replace by :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. * - Constant :data:`~oracledb.DEFAULT_AUTH` - - Replace by :data:`~oracledb.AUTH_MODE_DEFAULT`. + - Replace by :data:`oracledb.AUTH_MODE_DEFAULT`. * - Constant :data:`~oracledb.SYSASM` - - Replace by :data:`~oracledb.AUTH_MODE_SYSASM`. + - Replace by :data:`oracledb.AUTH_MODE_SYSASM`. * - Constant :data:`~oracledb.SYSBKP` - - Replace by :data:`~oracledb.AUTH_MODE_SYSBKP`. + - Replace by :data:`oracledb.AUTH_MODE_SYSBKP`. * - Constant :data:`~oracledb.SYSDBA` - - Replace by :data:`~oracledb.AUTH_MODE_SYSDBA`. + - Replace by :data:`oracledb.AUTH_MODE_SYSDBA`. * - Constant :data:`~oracledb.SYSDGD` - - Replace by :data:`~oracledb.AUTH_MODE_SYSDGD`. + - Replace by :data:`oracledb.AUTH_MODE_SYSDGD`. * - Constant :data:`~oracledb.SYSKMT` - - Replace by :data:`~oracledb.AUTH_MODE_SYSKMT`. + - Replace by :data:`oracledb.AUTH_MODE_SYSKMT`. * - Constant :data:`~oracledb.SYSOPER` - - Replace by :data:`~oracledb.AUTH_MODE_SYSOPER`. + - Replace by :data:`oracledb.AUTH_MODE_SYSOPER`. * - Constant :data:`~oracledb.SYSRAC` - - Replace by :data:`~oracledb.AUTH_MODE_SYSRAC`. + - Replace by :data:`oracledb.AUTH_MODE_SYSRAC`. * - Constant :data:`~oracledb.PRELIM_AUTH` - - Replace by :data:`~oracledb.AUTH_MODE_PRELIM`. + - Replace by :data:`oracledb.AUTH_MODE_PRELIM`. * - Constant :data:`~oracledb.SUBSCR_PROTO_OCI` - - Replace by :data:`~oracledb.SUBSCR_PROTO_CALLBACK`. - * - Class name `ObjectType `_ + - Replace by :data:`oracledb.SUBSCR_PROTO_CALLBACK`. + * - Class name ObjectType - Replace by the equivalent :ref:`DbObjectType`. - * - Class name `Object `_ + * - Class name Object - Replace by the equivalent :ref:`DbObject `. -Many of the usages deprecated in cx_Oracle (see tables below) are still -supported by python-oracledb to ease upgrade from cx_Oracle. However, these -previous cx_Oracle deprecation announcements remain in force for -python-oracledb. The relevant functionality may be removed in a future version -of python-oracledb. - -Some of the previous deprecations that have been removed and are not available in -python-oracledb are listed below: - -- The previously deprecated function `Cursor.fetchraw() `__ has been removed in - python-oracledb. Use one of the other fetch methods such as :meth:`Cursor.fetchmany()` - instead. - -- The previously deprecated function `Cursor.executemanyprepared() `__ has been removed - in python-oracledb. Use :meth:`Cursor.executemany()` instead. - -- The previously deprecated function `Cursor.rowcount() `__ has been removed - in python-oracledb. Use :meth:`Cursor.executemany()` instead. - -- The previously deprecated Advanced Queuing (AQ) API has been removed in - python-oracledb. Use the new AQ API instead. AQ is only available in the - python-oracledb Thick mode. - - - Replace `Connection.deq() `__ with :meth:`Queue.deqone()` or :meth:`Queue.deqmany()`. - - - Replace `Connection.deqoptions() `__ with :meth:`Queue.deqoptions()`. - - - Replace `Connection.enq() `__ with :meth:`Queue.enqone()` or :meth:`Queue.enqmany()`. +.. list-table-with-summary:: Desupported in python-oracledb 1.0 + :header-rows: 1 + :class: wy-table-responsive + :summary: The first column, Name, displays the desupported feature. The second column, Comments, includes information about the desupport and the replacement to use, if applicable. + :name: _desupported_1 - - Replace `Connection.enqoptions() `__ with :meth:`Queue.enqoptions()`. + * - Name + - Comments + * - ``Cursor.fetchraw()`` + - Use one of the other fetch methods such as :meth:`Cursor.fetchmany()` instead. + * - ``Cursor.executemanyprepared()`` + - Use :meth:`Cursor.executemany()` instead. + * - Previously deprecated Advanced Queuing (AQ) API + - Use the new :ref:`AQ API ` instead. AQ is only available in the python-oracledb Thick mode. + * - ``Connection.deq()`` + - Replace with :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` + * - ``Connection.deqoptions()`` + - Replace with :attr:`Queue.deqoptions` + * - ``Connection.enq()`` + - Replace with :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` + * - ``Connection.enqoptions()`` + - Replace with :attr:`Queue.enqoptions` .. list-table-with-summary:: Deprecated in cx_Oracle 8.2 :header-rows: 1 :class: wy-table-responsive - :summary: The first column, Name, displays the deprecated API name. The second column, - Comments, includes information about when the API was deprecated and what API to use, - if applicable. + :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecation and the replacement to use, if applicable. :name: _deprecations_8_2 * - Name - Comments - * - ``encoding`` parameter to `cx_Oracle.connect() `_ + * - ``encoding`` parameter to ``cx_Oracle.connect()`` - No longer needed as the use of encodings other than UTF-8 is - deprecated. Encoding is handled internally between python-oracledb and Oracle - Database. - * - ``nencoding`` parameter to `cx_Oracle.connect() `_ + deprecated. Encoding is handled internally between python-oracledb and + Oracle Database. + * - ``nencoding`` parameter to ``cx_Oracle.connect()`` - No longer needed as the use of encodings other than UTF-8 is deprecated. - * - ``encoding`` parameter to `cx_Oracle.SessionPool() `_ + * - ``encoding`` parameter to ```cx_Oracle.SessionPool()`` - No longer needed as the use of encodings other than UTF-8 is deprecated. - * - ``nencoding`` parameter to `cx_Oracle.SessionPool() `_ + * - ``nencoding`` parameter to ``cx_Oracle.SessionPool()`` - No longer needed as the use of encodings other than UTF-8 is deprecated. * - Connection.maxBytesPerCharacter - No longer needed as the use of encodings other than UTF-8 is deprecated. The constant value 4 can be used instead. - * - Positional parameters to `cx_Oracle.connect() `_ + * - Positional parameters to ``cx_Oracle.connect()`` - Replace with keyword parameters in order to comply with the Python database API. - * - Positional parameters to `cx_Oracle.SessionPool() `_ + * - Positional parameters to ``cx_Oracle.SessionPool()`` - Replace with keyword parameters in order to comply with the Python database API. - * - ``threaded`` parameter to `cx_Oracle.SessionPool() `_ + * - ``threaded`` parameter to ``cx_Oracle.SessionPool()`` - The value of this parameter is ignored. Threading is now always used. - * - ``waitTimeout`` parameter to `cx_Oracle.SessionPool() `_ + * - ``waitTimeout`` parameter to ``cx_Oracle.SessionPool()`` - Replace with parameter name ``wait_timeout`` - * - ``maxLifetimeSession`` parameter to `cx_Oracle.SessionPool() `_ + * - ``maxLifetimeSession`` parameter to ``cx_Oracle.SessionPool()`` - Replace with parameter name ``max_lifetime_session`` - * - ``sessionCallback`` parameter to `cx_Oracle.SessionPool() `_ + * - ``sessionCallback`` parameter to ``cx_Oracle.SessionPool()`` - Replace with parameter name ``session_callback`` - * - ``maxSessionsPerShard`` parameter to `cx_Oracle.SessionPool() `_ + * - ``maxSessionsPerShard`` parameter to ``cx_Oracle.SessionPool()`` - Replace with parameter name ``max_sessions_per_shard`` * - ``SessionPool.tnsentry`` - - Replace with `SessionPool.dsn `_ - * - ``payloadType`` parameter to `Connection.queue() `_ + - Replace with :attr:`ConnectionPool.dsn` + * - ``payloadType`` parameter to ``Connection.queue()`` - Replace with parameter name ``payload_type`` if using keyword parameters. - * - ``ipAddress`` parameter to `Connection.subscribe() `_ + * - ``ipAddress`` parameter to ``Connection.subscribe()`` - Replace with parameter name ``ip_address`` - * - ``groupingClass`` parameter to `Connection.subscribe() `_ + * - ``groupingClass`` parameter to ``Connection.subscribe()`` - Replace with parameter name ``grouping_class`` - * - ``groupingValue`` parameter to `Connection.subscribe() `_ + * - ``groupingValue`` parameter to ``Connection.subscribe()`` - Replace with parameter name ``grouping_value`` - * - ``groupingType`` parameter to `Connection.subscribe() `_ + * - ``groupingType`` parameter to ``Connection.subscribe()`` - Replace with parameter name ``grouping_type`` - * - ``clientInitiated`` parameter to `Connection.subscribe() `_ + * - ``clientInitiated`` parameter to ``Connection.subscribe()`` - Replace with parameter name ``client_initiated`` * - ``Connection.callTimeout`` - - Replace with `Connection.call_timeout `_ + - Replace with :attr:`Connection.call_timeout` * - ``Connection.tnsentry`` - - Replace with `Connection.dsn `_ - * - `keywordParameters` parameter to `Cursor.callfunc() `_ + - Replace with :attr:`Connection.dsn` + * - `keywordParameters` parameter to ``Cursor.callfunc()`` - Replace with parameter name ``keyword_parameters`` - * - ``keywordParameters`` parameter to `Cursor.callproc() `_ + * - ``keywordParameters`` parameter to ``Cursor.callproc()`` - Replace with parameter name ``keyword_parameters`` - * - ``encodingErrors`` parameter to `Cursor.var() `_ + * - ``encodingErrors`` parameter to ``Cursor.var()`` - Replace with parameter name ``encoding_errors`` * - ``Cursor.fetchraw()`` - - Replace with `Cursor.fetchmany() `_ - * - ``newSize`` parameter to `LOB.trim() `_ + - Replace with :meth:`Cursor.fetchmany()` + * - ``newSize`` parameter to ``LOB.trim()`` - Replace with parameter name ``new_size`` - * - ``Queue.deqMany`` - - Replace with `Queue.deqmany() `_ - * - ``Queue.deqOne`` - - Replace with `Queue.deqone() `_ - * - ``Queue.enqMany`` - - Replace with `Queue.enqmany() `_ - * - ``Queue.enqOne`` - - Replace with `Queue.enqone() `_ + * - ``Queue.deqMany()`` + - Replace with :meth:`Queue.deqmany()` + * - ``Queue.deqOne()`` + - Replace with :meth:`Queue.deqone()` + * - ``Queue.enqMany()`` + - Replace with :meth:`Queue.enqmany()` + * - ``Queue.enqOne()`` + - Replace with :meth:`Queue.enqone()` * - ``Queue.deqOptions`` - - Replace with `Queue.deqoptions `_ + - Replace with :attr:`Queue.deqoptions` * - ``Queue.enqOptions`` - - Replace with `Queue.enqoptions `_ + - Replace with :attr:`Queue.enqoptions` * - ``Queue.payloadType`` - - Replace with `Queue.payload_type `_ + - Replace with :attr:`Queue.payload_type` * - ``Subscription.ipAddress`` - - Replace with `Subscription.ip_address `_ + - Replace with :attr:`Subscription.ip_address` * - ``Message.consumerName`` - - Replace with `Message.consumer_name `_ + - Replace with :attr:`Message.consumer_name` * - ``Message.queueName`` - - Replace with `Message.queue_name `_ + - Replace with :attr:`Message.queue_name` * - ``Variable.actualElements`` - - Replace with `Variable.actual_elements `_ + - Replace with :attr:`Variable.actual_elements` * - ``Variable.bufferSize`` - - Replace with `Variable.buffer_size `_ + - Replace with :attr:`Variable.buffer_size` * - ``Variable.numElements`` - - Replace with `Variable.num_elements `_ + - Replace with :attr:`Variable.num_elements` .. list-table-with-summary:: Deprecated in cx_Oracle 8.0 :header-rows: 1 :class: wy-table-responsive - :summary: The first column, Name, displays the deprecated API name. The second column, Comments, includes information about when the API was deprecated and what API to use, if applicable. + :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecation and the replacement to use, if applicable. :name: _deprecations_8_0 * - Name - Comments * - ``cx_Oracle.BFILE`` - - Replace with `cx_Oracle.DB_TYPE_BFILE `_ + - Replace with :attr:`oracledb.DB_TYPE_BFILE` * - ``cx_Oracle.BLOB`` - - Replace with `cx_Oracle.DB_TYPE_BLOB `_ + - Replace with :attr:`oracledb.DB_TYPE_BLOB` * - ``cx_Oracle.BOOLEAN`` - - Replace with `cx_Oracle.DB_TYPE_BOOLEAN `_ + - Replace with :attr:`oracledb.DB_TYPE_BOOLEAN` * - ``cx_Oracle.CLOB`` - - Replace with `cx_Oracle.DB_TYPE_CLOB `_ + - Replace with :attr:`oracledb.DB_TYPE_CLOB` * - ``cx_Oracle.CURSOR`` - - Replace with `cx_Oracle.DB_TYPE_CURSOR `_ + - Replace with :attr:`oracledb.DB_TYPE_CURSOR` * - ``cx_Oracle.FIXED_CHAR`` - - Replace with `cx_Oracle.DB_TYPE_CHAR `_ + - Replace with :attr:`oracledb.DB_TYPE_CHAR` * - ``cx_Oracle.FIXED_NCHAR`` - - Replace with `cx_Oracle.DB_TYPE_NCHAR `_ + - Replace with :attr:`oracledb.DB_TYPE_NCHAR` * - ``cx_Oracle.INTERVAL`` - - Replace with `cx_Oracle.DB_TYPE_INTERVAL_DS `_ + - Replace with :attr:`oracledb.DB_TYPE_INTERVAL_DS` * - ``cx_Oracle.LONG_BINARY`` - - Replace with `cx_Oracle.DB_TYPE_LONG_RAW `_ + - Replace with :attr:`oracledb.DB_TYPE_LONG_RAW` * - ``cx_Oracle.LONG_STRING`` - - Replace with `cx_Oracle.DB_TYPE_LONG `_ + - Replace with :attr:`oracledb.DB_TYPE_LONG` * - ``cx_Oracle.NATIVE_FLOAT`` - - Replace with `cx_Oracle.DB_TYPE_BINARY_DOUBLE `_ + - Replace with :attr:`oracledb.DB_TYPE_BINARY_DOUBLE` * - ``cx_Oracle.NATIVE_INT`` - - Replace with `cx_Oracle.DB_TYPE_BINARY_INTEGER `_ + - Replace with :attr:`oracledb.DB_TYPE_BINARY_INTEGER` * - ``cx_Oracle.NCHAR`` - - Replace with `cx_Oracle.DB_TYPE_NVARCHAR `_ + - Replace with :attr:`oracledb.DB_TYPE_NVARCHAR` * - ``cx_Oracle.NCLOB`` - - Replace with `cx_Oracle.DB_TYPE_NCLOB `_ + - Replace with :attr:`oracledb.DB_TYPE_NCLOB` * - ``cx_Oracle.OBJECT`` - - Replace with `cx_Oracle.DB_TYPE_OBJECT `_ + - Replace with :attr:`oracledb.DB_TYPE_OBJECT` * - ``cx_Oracle.TIMESTAMP`` - - Replace with `cx_Oracle.DB_TYPE_TIMESTAMP `_ + - Replace with :attr:`oracledb.DB_TYPE_TIMESTAMP` .. list-table-with-summary:: Deprecated in cx_Oracle 7.2 :header-rows: 1 :class: wy-table-responsive - :summary: The first column, Name, displays the deprecated API name. The second column, Comments, includes information about when the API was deprecated and what API to use, if applicable. + :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecation and the replacement to use, if applicable. :name: _deprecations_7_2 * - Name - Comments * - ``Connection.deq()`` - - Replace with `Queue.deqone() `_ or `Queue.deqmany() `_. + - Replace with :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` * - ``Connection.deqoptions()`` - - Replace with attribute `Queue.deqoptions `_. + - Replace with attribute :attr:`Queue.deqoptions` * - ``Connection.enq()`` - - Replace with `Queue.enqone() `_ or `Queue.enqmany() `_. + - Replace with :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` * - ``Connection.enqoptions()`` - - Replace with attribute `Queue.enqoptions `_. + - Replace with attribute :attr:`Queue.enqoptions` .. list-table-with-summary:: Deprecated in cx_Oracle 6.4 :header-rows: 1 :class: wy-table-responsive - :summary: The first column, Name, displays the deprecated API name. The second column, Comments, includes information about when the API was deprecated and what API to use, if applicable. + :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecation and the replacement to use, if applicable. :name: _deprecations_6_4 * - Name - Comments * - ``Cursor.executemanyprepared()`` - - Replace with `~Cursor.executemany() `_ with None for the statement argument and an integer for the parameters argument. + - Replace with :meth:`Cursor.executemany()` using None for the ``statement`` argument and an integer for the ``parameters`` argument. diff --git a/doc/src/api_manual/fetch_info.rst b/doc/src/api_manual/fetch_info.rst new file mode 100644 index 00000000..9522560a --- /dev/null +++ b/doc/src/api_manual/fetch_info.rst @@ -0,0 +1,153 @@ +.. _fetchinfoobj: + +********************** +API: FetchInfo Objects +********************** + +FetchInfo objects are created internally when a query is executed. They are found +in the sequence :data:`Cursor.description`. There is one FetchInfo object for +each column. For compatibility with the Python Database API, this object +behaves as a 7-tuple containing the values for the attributes ``name``, +``type_code``, ``display_size``, ``internal_size``, ``precision``, ``scale``, +and ``null_ok`` in that order. For example, if ``fetch_info`` is of type +FetchInfo, then ``fetch_info[2]`` is the same as ``fetch_info.display_size``. + +.. dbapiobjectextension:: + +.. versionadded:: 1.4.0 + +FetchInfo Attributes +==================== + +.. attribute:: FetchInfo.annotations + + This read-only attribute returns a dictionary containing the `annotations + `__ associated with the fetched column. If + there are no annotations, the value *None* is returned. Annotations + require Oracle Database 23ai. If using python-oracledb Thick mode, Oracle + Client 23ai is also required. + + .. versionadded:: 2.0.0 + +.. attribute:: FetchInfo.display_size + + This read-only attribute returns the display size of the column as mandated + by the Python Database API. + +.. attribute:: FetchInfo.domain_name + + This read-only attribute returns the name of the `data use case domain + `__ associated with the fetched column. If + there is no data use case domain, the value *None* is returned. `Data + use case domains `__ require Oracle Database 23ai. + If using python-oracledb Thick mode, Oracle Client 23ai is also required. + + .. versionadded:: 2.0.0 + +.. attribute:: FetchInfo.domain_schema + + This read-only attribute returns the schema of the `data use case domain + `__ associated with the fetched column. If + there is no data use case domain, the value *None* is returned. `Data + use case domains `__ require Oracle Database 23ai. + If using python-oracledb Thick mode, Oracle Client 23ai is also required. + + .. versionadded:: 2.0.0 + +.. attribute:: FetchInfo.internal_size + + This read-only attribute returns the internal size of the column as + mandated by the Python Database API. + +.. attribute:: FetchInfo.is_json + + This read-only attribute returns whether the column is known to contain + JSON data. This will be *True* when the type code is + :data:`oracledb.DB_TYPE_JSON` as well as when an "IS JSON" constraint is + enabled on LOB and VARCHAR2 columns. + +.. attribute:: FetchInfo.is_oson + + This read-only attribute returns whether the column is known to contain + binary encoded `OSON `__ data. This will be *True* + when an "IS JSON FORMAT OSON" check constraint is enabled on BLOB columns. + + .. versionadded:: 2.1.0 + +.. attribute:: FetchInfo.name + + This read-only attribute returns the name of the column as mandated by the + Python Database API. + +.. attribute:: FetchInfo.null_ok + + This read-only attribute returns whether nulls are allowed in the column as + mandated by the Python Database API. + +.. attribute:: FetchInfo.precision + + This read-only attribute returns the precision of the column as mandated by + the Python Database API. + +.. attribute:: FetchInfo.scale + + This read-only attribute returns the scale of the column as mandated by + the Python Database API. + +.. attribute:: FetchInfo.type + + This read-only attribute returns the type of the column. This will be an + :ref:`Oracle Object Type ` if the column contains Oracle + objects; otherwise, it will be one of the :ref:`database type constants + ` defined at the module level. + + +.. attribute:: FetchInfo.type_code + + This read-only attribute returns the type of the column as mandated by the + Python Database API. The type will be one of the :ref:`database type + constants ` defined at the module level. + +.. attribute:: FetchInfo.vector_dimensions + + This read-only attribute returns the number of dimensions required by + VECTOR columns. If the column is not a VECTOR column or allows for any + number of dimensions, the value returned is *None*. + + .. versionadded:: 2.2.0 + +.. attribute:: FetchInfo.vector_format + + This read-only attribute returns the storage format used by VECTOR + columns. The value of this attribute can be: + + - :data:`oracledb.VECTOR_FORMAT_BINARY` which represents 8-bit unsigned + integers + - :data:`oracledb.VECTOR_FORMAT_INT8` which represents 8-bit signed + integers + - :data:`oracledb.VECTOR_FORMAT_FLOAT32` which represents 32-bit + floating-point numbers + - :data:`oracledb.VECTOR_FORMAT_FLOAT64` which represents 64-bit + floating-point numbers + + If the column is not a VECTOR column or allows for any type of storage, + the value returned is *None*. + + .. 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 eecaae24..5fcdceb9 100644 --- a/doc/src/api_manual/lob.rst +++ b/doc/src/api_manual/lob.rst @@ -4,12 +4,13 @@ API: LOB Objects **************** -See :ref:`lobdata` for more information about using LOBs. +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 =========== @@ -20,31 +21,26 @@ LOB Methods associated with the LOB can be updated -- but only if :meth:`~LOB.open()` was called first. - .. method:: LOB.fileexists() Returns a boolean indicating if the file referenced by the BFILE type LOB exists. - .. method:: LOB.getchunksize() Returns the chunk size for the internal LOB. Reading and writing to the LOB in chunks of multiples of this size will improve performance. - .. method:: LOB.getfilename() Returns a two-tuple consisting of the directory alias and file name for a BFILE type LOB. - .. method:: LOB.isopen() Returns a boolean indicating if the LOB has been opened using the method :meth:`~LOB.open()`. - .. method:: LOB.open() Opens the LOB for writing. This will improve performance when writing to a @@ -52,7 +48,6 @@ LOB Methods with the LOB. If this method is not called, each write will perform an open internally followed by a close after the write has been completed. - .. method:: LOB.read([offset=1, [amount]]) Returns a portion (or all) of the data in the LOB object. Note that the @@ -62,12 +57,10 @@ LOB Methods characters are in the LOB, the offset and amount will have to be chosen carefully to avoid splitting a character. - -.. method:: LOB.setfilename(dirAlias, name) +.. method:: LOB.setfilename(dir_alias, name) Sets the directory alias and name of the BFILE type LOB. - .. method:: LOB.size() Returns the size of the data in the LOB object. For BLOB and BFILE type @@ -75,12 +68,10 @@ LOB Methods number of UCS-2 code points. UCS-2 code points are equivalent to characters for all but supplemental characters. - .. method:: LOB.trim(new_size=0) Trims the LOB to the new size. - .. method:: LOB.write(data, offset=1) Writes the data to the LOB object at the given offset. The offset is in @@ -92,7 +83,7 @@ LOB Methods :meth:`~LOB.trim()` function. LOB Attributes -=============== +============== .. attribute:: LOB.type diff --git a/doc/src/api_manual/module.rst b/doc/src/api_manual/module.rst index 12e4684d..1bad3c95 100644 --- a/doc/src/api_manual/module.rst +++ b/doc/src/api_manual/module.rst @@ -11,18 +11,6 @@ API: python-oracledb Module Oracledb Methods ================ -.. data:: __future__ - - Special object which contains attributes which control the behavior of - python-oracledb, allowing for opting in for new features. No attributes are - currently supported so all attributes will silently ignore being set and - will always appear to have the value None. - - .. note:: - - This method is an extension to the DB API definition. - - .. function:: Binary(string) Constructs an object holding a binary (long) string value. @@ -34,29 +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 method is an extension to the DB API definition. - -.. function:: connect(dsn=None, pool=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=0, tcp_connect_timeout=60.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, handle=0) + 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`. + + .. 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, instance_name=None, sid=None, server_type=None, \ + cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, \ + retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, \ + ssl_server_dn_match=True, ssl_server_cert_dn=None, \ + wallet_location=None, events=False, externalauth=False, \ + mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \ + stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, \ + tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, \ + appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ + connection_id_prefix=None, ssl_context=None, sdu=8192, \ + pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ + program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ + terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, 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 @@ -79,13 +70,21 @@ Oracledb Methods ``params`` parameter object. Similar precedence rules also apply to other values. - The ``dsn`` (data source name) parameter can be a string in the format - ``user/password@connect_string`` or can simply be the connect string (in - which case authentication credentials such as the username and password - need to be specified separately). See :ref:`connstr` for more information. + The ``dsn`` (data source name) parameter is an :ref:`Oracle Net Services + Connection String `. It can also be a string in the format + ``user/password@connect_string``. + + The ``pool`` parameter is expected to be a pool object. This parameter + was deprecated in python-oracledb 3.0.0. Use + :meth:`ConnectionPool.acquire()` instead since the use of this parameter + is the equivalent of calling this method. - The ``pool`` parameter is expected to be a pool object. The use of this - parameter is the equivalent of calling :meth:`ConnectionPool.acquire()`. + The ``pool_alias`` parameter is expected to be a string which indicates the + name of the previously created pool in the :ref:`connection pool cache + ` from which to acquire the connection. This is identical to + calling :meth:`ConnectionPool.acquire()`. When ``pool_alias`` is used, + ``connect()`` supports the same parameters as + :meth:`~ConnectionPool.acquire()` and has the same behavior. The ``conn_class`` parameter is expected to be Connection or a subclass of Connection. @@ -93,147 +92,158 @@ Oracledb Methods The ``params`` parameter is expected to be of type :ref:`ConnectParams ` and contains connection parameters that will be used when establishing the connection. If this parameter is not specified, the - additional keyword parameters will be used to create an instance of - ConnectParams. If both the params parameter and additional keyword + additional keyword parameters will be used to internally create an instance + of ConnectParams. If both the params parameter and additional keyword parameters are specified, the values in the keyword parameters have - precedence. Note that if a ``dsn`` is also supplied, then in the - python-oracledb Thin mode, the values of the parameters specified (if any) - within the ``dsn`` will override the values passed as additional keyword - parameters, which themselves override the values set in the ``params`` - parameter object. + precedence. Note that if a ``dsn`` is also supplied in python-oracledb Thin + mode, then the values of the parameters specified (if any) within the + ``dsn`` will override the values passed as additional keyword parameters, + which themselves override the values set in the ``params`` parameter + object. The ``user`` parameter is expected to be a string which indicates the name of the user to connect to. This value is used in both the python-oracledb Thin and Thick modes. The ``proxy_user`` parameter is expected to be a string which indicates the - name of the proxy user to connect to. If this value is not specified, it will - be parsed out of user if user is in the form "user[proxy_user]". This value is - used in both the python-oracledb Thin and Thick modes. + name of the proxy user to connect to. If this value is not specified, it + will be parsed out of user if user is in the form "user[proxy_user]". This + value is used in both the python-oracledb Thin and Thick modes. - The ``password`` parameter expected to be a string which indicates the password - for the user. This value is used in both the python-oracledb Thin and Thick modes. + The ``password`` parameter expected to be a string which indicates the + password for the user. This value is used in both the python-oracledb Thin + and Thick modes. - The ``newpassword`` parameter is expected to be a string which indicates the new - password for the user. The new password will take effect immediately upon a - successful connection to the database. This value is used in both the - python-oracledb Thin and Thick modes. + The ``newpassword`` parameter is expected to be a string which indicates + the new password for the user. The new password will take effect + immediately upon a successful connection to the database. This value is + used in both the python-oracledb Thin and Thick modes. - The ``wallet_password`` parameter is expected to be a string which indicates the - password to use to decrypt the PEM-encoded wallet, if it is encrypted. This - value is only used in python-oracledb Thin mode. The ``wallet_password`` parameter - is not needed for cwallet.sso files that are used in the python-oracledb Thick - mode. + The ``wallet_password`` parameter is expected to be a string which + indicates the password to use to decrypt the PEM-encoded wallet, if it is + encrypted. This value is only used in python-oracledb Thin mode. The + ``wallet_password`` parameter is not needed for cwallet.sso files that are + used in the python-oracledb Thick mode. The ``access_token`` parameter is expected to be a string or a 2-tuple or a callable. If it is a string, it specifies an Azure AD OAuth2 token used for Open Authorization (OAuth 2.0) token based authentication. If it is a 2-tuple, it specifies the token and private key strings used for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based - authentication. If it is a callable, it returns either a string or a 2-tuple - used for OAuth 2.0 or OCI IAM token based authentication and is useful when - the pool needs to expand and create new connections but the current - authentication token has expired. This value is used in both the + authentication. If it is a callable, it returns either a string or a + 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is + useful when the pool needs to expand and create new connections but the + current authentication token has expired. This value is used in both the python-oracledb Thin and Thick modes. - The ``host`` parameter is expected to be a string which specifies the name or IP - address of the machine hosting the listener, which handles the initial - connection to the database. This value is used in both the python-oracledb - Thin and Thick modes. - - The ``port`` parameter is expected to be an integer which indicates the port number - on which the listener is listening. The default value is 1521. This value is used - in both the python-oracledb Thin and Thick modes. - - The ``protocol`` parameter is expected to be one of the strings "tcp" or "tcps" - which indicates whether to use unencrypted network traffic or encrypted network - traffic (TLS). The default value is tcp. This value is used in both the + The ``host`` parameter is expected to be a string which specifies the name + or IP address of the machine hosting the listener, which handles the + initial connection to the database. This value is used in both the python-oracledb Thin and Thick modes. - The ``https_proxy`` parameter is expected to be a string which indicates the name - or IP address of a proxy host to use for tunneling secure connections. This value - is used in both the python-oracledb Thin and Thick modes. + The ``port`` parameter is expected to be an integer which indicates the + port number on which the listener is listening. The default value is + *1521*. This value is used in both the python-oracledb Thin and Thick + modes. - The ``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 ``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 ``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 + The ``https_proxy`` parameter is expected to be a string which indicates + the name or IP address of a proxy host to use for tunneling secure + connections. This value is used in both the python-oracledb Thin and Thick modes. - The ``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 ``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 ``server_type`` parameter is expected to be a string that indicates the type - of server connection that should be established. If specified, it should be one - of `dedicated`, `shared`, or `pooled`. This value is used in both the + 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 ``cclass`` parameter is expected to be a string that identifies the connection - class to use for Database Resident Connection Pooling (DRCP). This value is used - in both the python-oracledb Thin and Thick modes. + The ``instance_name`` parameter is expected to be a string which indicates + the instance name of the database. This value is used in both the + python-oracledb Thin and Thick modes. + + The ``sid`` parameter is expected to be a string which indicates the SID of + the database. It is recommended to use ``service_name`` instead. This value + is used in both the python-oracledb Thin and Thick modes. + + The ``server_type`` parameter is expected to be a string that indicates the + type of server connection that should be established. If specified, it + should be one of *dedicated*, *shared*, or *pooled*. This value is used in + both the python-oracledb Thin and Thick modes. - The ``purity`` parameter is expected to be one of the :ref:`oracledb.PURITY_* - ` constants that identifies the purity to use for - DRCP. This value is used in both the python-oracledb Thin and Thick modes. - The purity will internally default to :data:`~oracledb.PURITY_SELF` - for pooled connections. For standalone connections, the purity will - internally default to :data:`~oracledb.PURITY_NEW`. + The ``cclass`` parameter is expected to be a string that identifies the + connection class to use for :ref:`drcp`. This value is used in both the + python-oracledb Thin and Thick modes. - The ``expire_time`` parameter is expected to be an integer which indicates the - number of minutes between the sending of keepalive probes. If this parameter - is set to a value greater than zero it enables keepalive. This value is used - in both the python-oracledb Thin and Thick modes. The default value is 0. + The ``purity`` parameter is expected to be one of the + :ref:`oracledb.PURITY_* ` constants that identifies the + purity to use for DRCP. This value is used in both the python-oracledb Thin + and Thick modes. The purity will internally default to + :data:`~oracledb.PURITY_SELF` for pooled connections. For standalone + connections, the purity will internally default to + :data:`~oracledb.PURITY_NEW`. + + The ``expire_time`` parameter is expected to be an integer which indicates + the number of minutes between the sending of keepalive probes. If this + parameter is set to a value greater than zero it enables keepalive. This + value is used in both the python-oracledb Thin and Thick modes. The default + value is *0*. The ``retry_count`` parameter is expected to be an integer that identifies the number of times that a connection attempt should be retried before the attempt is terminated. This value is used in both the python-oracledb Thin - and Thick modes. The default value is 0. + 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 + 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 0. - - 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 60.0. - - The ``ssl_server_dn_match`` parameter is expected to be a boolean that indicates - whether the server certificate distinguished name (DN) should be matched in - addition to the regular certificate verification that is performed. Note that - if the ``ssl_server_cert_dn`` parameter is not provided, host name matching - is performed instead. This value is used in both the python-oracledb Thin and - Thick modes. The default value is True. - - The ``ssl_server_cert_dn`` parameter is expected to be a string that indicates - the distinguished name (DN) which should be matched with the server. This - value is ignored if the ``ssl_server_dn_match`` parameter is not set to the - value True. This value is used in both the python-oracledb Thin and Thick - modes. + value is *1*. - The ``wallet_location`` parameter is expected to be a string that identifies - the directory where the wallet can be found. In python-oracledb Thin mode, - this must be the directory of the PEM-encoded wallet file, ewallet.pem. - In python-oracledb Thick mode, this must be the directory of the file, - cwallet.sso. This value is used in both the python-oracledb Thin and Thick - modes. + The ``tcp_connect_timeout`` parameter is expected to be a float that + indicates the maximum number of seconds to wait for establishing a + connection to the database host. This value is used in both the + python-oracledb Thin and Thick modes. The default value is *20.0*. + + The ``ssl_server_dn_match`` parameter is expected to be a boolean that + indicates whether the server certificate distinguished name (DN) should be + matched in addition to the regular certificate verification that is + performed. Note that if the ``ssl_server_cert_dn`` parameter is not + provided, host name matching is performed instead. This value is used in + both the python-oracledb Thin and Thick modes. The default value is *True*. + + The ``ssl_server_cert_dn`` parameter is expected to be a string that + indicates the distinguished name (DN) which should be matched with the + server. This value is ignored if the ``ssl_server_dn_match`` parameter is + not set to the value *True*. This value is used in both the python-oracledb + Thin and Thick modes. + + The ``wallet_location`` parameter is expected to be a string that + identifies the directory where the wallet can be found. In python-oracledb + Thin mode, this must be the directory of the PEM-encoded wallet file, + ewallet.pem. In python-oracledb Thick mode, this must be the directory of + the file, cwallet.sso. This value is used in both the python-oracledb Thin + and Thick modes. The ``events`` parameter is expected to be a boolean that specifies whether the events mode should be enabled. This value is only used in the - python-oracledb Thick mode. This parameter is needed for continuous - query notification and high availability event notifications. The default - value is False. + python-oracledb Thick mode and is ignored in the Thin mode. This parameter + is needed for continuous query notification and high availability event + notifications. The default value is *False*. The ``externalauth`` parameter is a boolean that specifies whether external - authentication should be used. This value is only used in the python-oracledb - Thick mode. 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. + authentication should be used. This value is only used in the + python-oracledb Thick mode and is ignored in the Thin mode. The default + value is *False*. For standalone connections, external authentication + occurs when the ``user`` and ``password`` attributes are not used. If these + attributes are not used, you can optionally set the ``externalauth`` + attribute to *True*, which may aid code auditing. If the ``mode`` parameter is specified, it must be one of the :ref:`connection authorization modes ` @@ -244,68 +254,587 @@ 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 both the - python-oracledb Thin and Thick modes. The default is the value of + The ``stmtcachesize`` parameter is expected to be an integer which + specifies the initial size of the statement cache. This value is used in + both the python-oracledb Thin and Thick modes. The default is the value of :attr:`defaults.stmtcachesize`. The ``edition`` parameter is expected to be a string that indicates the - edition to use for the connection. This parameter cannot be used - simultaneously with the ``cclass`` parameter. This value is used in the - python-oracledb Thick mode. + edition to use for the connection. It requires Oracle Database 11.2, or + later. This parameter cannot be used simultaneously with the ``cclass`` + parameter. - The ``tag`` parameter is expected to be a string that identifies the type of - connection that should be returned from a pool. This value is only used - in the python-oracledb Thick mode. + The ``tag`` parameter is expected to be a string that identifies the type + of connection that should be returned from a pool. This value is only used + in the python-oracledb Thick mode and is ignored in the Thin mode. - The ``matchanytag`` parameter is expected to be a boolean specifying whether - any tag can be used when acquiring a connection from the pool. This value - is only used in the python-oracledb Thick mode when acquiring a connection - from a pool. The default value is False. + The ``matchanytag`` parameter is expected to be a boolean specifying + whether any tag can be used when acquiring a connection from the pool. This + value is only used in the python-oracledb Thick mode when acquiring a + connection from a pool. This value is ignored in the python-oracledb Thin + mode. The default value is *False*. The ``config_dir`` parameter is expected to be a string that indicates the - directory in which 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 should contain - namespace, name, and value and each entry in the tuple should be a string. - This value is only used in the python-oracledb Thick mode. + The ``appcontext`` parameter is expected to be a list of 3-tuples that + identifies the application context used by the connection. This parameter + should contain namespace, name, and value and each entry in the tuple + should be a string. - The ``shardingkey`` parameter and ``supershardingkey`` parameters, if specified, - are expected to be a sequence of values which identifies the database shard to - connect to. The key values can be a list of strings, numbers, bytes, or dates. - This value is only used in the python-oracledb Thick mode. + The ``shardingkey`` parameter and ``supershardingkey`` parameters, if + specified, are expected to be a sequence of values which identifies the + database shard to connect to. The key values can be a list of strings, + numbers, bytes, or dates. These values are only used in the + python-oracledb Thick mode and are ignored in the Thin mode. See + :ref:`connsharding`. The ``debug_jdwp`` parameter is expected to be a string with the format - `host=;port=` that specifies the host and port of the PL/SQL debugger. - This allows using the Java Debug Wire Protocol (JDWP) to debug PL/SQL code called - by python-oracledb. This value is only used in the python-oracledb Thin mode. - For python-oracledb Thick mode, set the ``ORA_DEBUG_JDWP`` environment variable - which has the same syntax. For more information, see :ref:`applntracing`. + `host=;port=` that specifies the host and port of the PL/SQL + debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug + PL/SQL code called by python-oracledb. This value is only used in the + python-oracledb Thin mode. For python-oracledb Thick mode, set the + ``ORA_DEBUG_JDWP`` environment variable which has the same syntax. For more + information, see :ref:`applntracing`. + + The ``connection_id_prefix`` parameter is expected to be a string and is + added to the beginning of the generated ``connection_id`` that is sent to + the database for `tracing `__. This value + is only used in the python-oracledb Thin mode. + + The ``ssl_context`` parameter is expected to be an `SSLContext object + `__ which is used + for connecting to the database using TLS. This SSL context will be + modified to include the private key or any certificates found in a + separately supplied wallet. This parameter should only be specified if + the default SSLContext object cannot be used. This value is only used in + the python-oracledb Thin mode. + + The ``sdu`` parameter is expected to be an integer that returns the + requested size of the Session Data Unit (SDU), in bytes. The value tunes + internal buffers used for communication to the database. Bigger values can + increase throughput for large queries or bulk data loads, but at the cost + of higher memory use. The SDU size that will actually be used is negotiated + down to the lower of this value and the database network SDU configuration + value. See the `Database Net Services documentation `__ for more details. This value is used in both the + python-oracledb Thin and Thick modes. The default value is *8192* bytes. + + The ``pool_boundary`` parameter is expected to be one of the strings + *statement* or *transaction* which indicates when pooled :ref:`DRCP ` + or PRCP connections can be returned to the pool. If the value is + *statement*, then pooled DRCP or PRCP connections are implicitly released + back to the DRCP or PRCP pool when the connection is stateless (that is, + there are no active cursors, active transactions, temporary tables, or + temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP + connections are implicitly released back to the DRCP or PRCP pool when + either one of the methods :meth:`Connection.commit()` or + :meth:`Connection.rollback()` are called. This parameter requires the use + of DRCP or PRCP with Oracle Database 23ai (or later). See + :ref:`implicitconnpool` for more information. This value is used in both + the python-oracledb Thin and Thick modes. + + The ``use_tcp_fast_open`` parameter is expected to be a boolean which + indicates whether to use TCP Fast Open which is an `Oracle Autonomous + Database Serverless (ADB-S) `__ specific feature that can + reduce the latency in round-trips to the database after a connection has + been established. This feature is only available with certain versions of + ADB-S. This value is used in both python-oracledb Thin and Thick modes. + The default value is *False*. + + The ``ssl_version`` parameter is expected to be one of the constants + *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the + TLS protocol version used. These constants are defined in the Python + `ssl `__ module. This + parameter can be specified when establishing connections with the protocol + *tcps*. This value is used in both python-oracledb Thin and Thick modes. + The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you + are using python-oracledb Thick mode, Oracle Client 23ai is additionally + required. + + The ``use_sni`` parameter is expected to be a boolean which indicates + whether to use the TLS Server Name Indication (SNI) extension to bypass the + second TLS negotiation that would otherwise be required. This parameter is + used in both python-oracledb Thin and Thick modes. This parameter requires + Oracle Database 23.7. The default value is *False*. See the `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 + default is the value of :attr:`defaults.program`. + + The ``machine`` parameter is expected to be a string which specifies the + machine name of the client connecting to Oracle Database. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.machine`. + + The ``terminal`` parameter is expected to be a string which specifies the + terminal identifier from which the connection originates. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.terminal`. + + The ``osuser`` parameter is expected to be a string which specifies the + operating system user that initiates the database connection. This value + is only used in the python-oracledb Thin mode. The default value is the + value of :attr:`defaults.osuser`. + + The ``driver_name`` parameter is expected to be a string which specifies + the driver used by the client to connect to Oracle Database. This value + is used in both the python-oracledb Thin and Thick modes. The default is + the value of :attr:`defaults.driver_name`. + + The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean + which indicates whether the connect string should be passed unchanged to + the Oracle Client libraries for parsing when using python-oracledb Thick + mode. If this parameter is set to *False* in Thick mode, connect strings + are parsed by python-oracledb itself and a generated connect descriptor is + sent to the Oracle Client libraries. This value is only used in the + python-oracledb Thick mode. The default value is the value of + :attr:`defaults.thick_mode_dsn_passthrough`. For more information, see + :ref:`usingconfigfiles`. + + The ``extra_auth_params`` parameter is expected to be a dictionary + containing the configuration parameters necessary for Oracle Database + authentication using :ref:`OCI ` or :ref:`Azure + ` cloud native authentication plugins. This value is + used in both the python-oracledb Thin and Thick modes. See + :ref:`tokenauth`. + + The ``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. It - should be used with extreme caution. The default value is 0. + 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*. -.. 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=0, tcp_connect_timeout=60.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, handle=0) + .. versionchanged:: 3.2.0 + + The ``pool_name`` parameter was added. + + .. versionchanged:: 3.0.0 + + 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 + + The ``program``, ``machine``, ``terminal``, ``osuser``, and + ``driver_name`` parameters were added. Support for ``edition`` and + ``appcontext`` was added to python-oracledb Thin mode. + + .. versionchanged:: 2.3.0 + + The default value of the ``retry_delay`` parameter was changed from 0 + seconds to 1 second. The default value of the ``tcp_connect_timeout`` + parameter was changed from 60.0 seconds to 20.0 seconds. The + ``ssl_version`` parameter was added. + + .. versionchanged:: 2.1.0 + + The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. + + .. versionchanged:: 2.0.0 - Contains all the parameters that can be used to establish a connection to the database. + The ``ssl_context`` and ``sdu`` parameters were added. + + .. versionchanged:: 1.4.0 + + The ``connection_id_prefix`` parameter was added. + +.. function:: connect_async(dsn=None, pool=None, pool_alias=None, \ + conn_class=None, params=None, user=None, proxy_user=None, \ + password=None, newpassword=None, wallet_password=None, \ + access_token=None, host=None, port=1521, protocol="tcp", \ + https_proxy=None, https_proxy_port=0, service_name=None, \ + instance_name=None, sid=None, server_type=None, cclass=None, \ + purity=oracledb.PURITY_DEFAULT, expire_time=0, retry_count=0, \ + retry_delay=1, tcp_connect_timeout=20.0, ssl_server_dn_match=True, \ + ssl_server_cert_dn=None, wallet_location=None, events=False, \ + externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, \ + disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, \ + edition=None, tag=None, matchanytag=False, \ + config_dir=oracledb.defaults.config_dir, appcontext=[], \ + shardingkey=[], supershardingkey=[], debug_jdwp=None, \ + connection_id_prefix=None, ssl_context=None, sdu=8192, \ + pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ + program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ + terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=0) + + Constructor for creating a connection to the database. Returns an + :ref:`AsyncConnection Object `. All parameters are optional + and can be specified as keyword parameters. See + :ref:`standaloneconnection` information about connections. + + This method can only be used in python-oracledb Thin mode. + + When connecting to Oracle Autonomous Database, use Python 3.11, or later. + + .. versionadded:: 2.0.0 + + Some values, such as the database host name, can be specified as + parameters, as part of the connect string, and in the params object. + The precedence is that values in the ``dsn`` parameter override values + passed as individual parameters, which themselves override values set in + the ``params`` parameter object. Similar precedence rules also apply to + other values. + + The ``dsn`` (data source name) parameter is an :ref:`Oracle Net Services + Connection String `. It can also be a string in the format + ``user/password@connect_string``. + + The ``pool`` parameter is expected to be an AsyncConnectionPool object. + This parameter was deprecated in python-oracledb 3.0.0. Use + :meth:`AsyncConnectionPool.acquire()` instead since the + use of this parameter is the equivalent of calling this method. + + The ``pool_alias`` parameter is expected to be a string which indicates the + name of the previously created pool in the :ref:`connection pool cache + ` from which to acquire the connection. This is identical to + calling :meth:`AsyncConnectionPool.acquire()`. When ``pool_alias`` is used, + ``connect_async()`` supports the same parameters as + :meth:`~AsyncConnectionPool.acquire()` and has the same behavior. + + The ``conn_class`` parameter is expected to be AsyncConnection or a + subclass of AsyncConnection. + + The ``params`` parameter is expected to be of type :ref:`ConnectParams + ` and contains connection parameters that will be used when + establishing the connection. If this parameter is not specified, the + additional keyword parameters will be used to create an instance of + ConnectParams. If both the params parameter and additional keyword + parameters are specified, the values in the keyword parameters have + precedence. Note that if a ``dsn`` is also supplied, then the values of the + parameters specified (if any) within the ``dsn`` will override the values + passed as additional keyword parameters, which themselves override the + values set in the ``params`` parameter object. + + The ``user`` parameter is expected to be a string which indicates the name + of the user to connect to. + + The ``proxy_user`` parameter is expected to be a string which indicates the + name of the proxy user to connect to. If this value is not specified, it + will be parsed out of user if user is in the form "user[proxy_user]". + + The ``password`` parameter expected to be a string which indicates the + password for the user. + + The ``newpassword`` parameter is expected to be a string which indicates + the new password for the user. The new password will take effect + immediately upon a successful connection to the database. + + The ``wallet_password`` parameter is expected to be a string which + indicates the password to use to decrypt the PEM-encoded wallet, if it is + encrypted. + + The ``access_token`` parameter is expected to be a string or a 2-tuple or + a callable. If it is a string, it specifies an Azure AD OAuth2 token used + for Open Authorization (OAuth 2.0) token based authentication. If it is a + 2-tuple, it specifies the token and private key strings used for Oracle + Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based + authentication. If it is a callable, it returns either a string or a + 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is + useful when the pool needs to expand and create new connections but the + current authentication token has expired. + + The ``host`` parameter is expected to be a string which specifies the name + or IP address of the machine hosting the listener, which handles the + initial connection to the database. + + The ``port`` parameter is expected to be an integer which indicates the + port number on which the listener is listening. The default value is + *1521*. + + The ``protocol`` parameter is expected to be one of the strings *tcp* or + *tcps* which indicates whether to use unencrypted network traffic or + encrypted network traffic (TLS). The default value is *tcp*. + + The ``https_proxy`` parameter is expected to be a string which indicates + the name or IP address of a proxy host to use for tunneling secure + connections. + + The ``https_proxy_port`` parameter is expected to be an integer which + indicates the port that is to be used to communicate with the proxy host. + The default value is *0*. + + The ``service_name`` parameter is expected to be a string which indicates + the service name of the database. + + The ``instance_name`` parameter is expected to be a string which indicates + the instance name of the database. + + The ``sid`` parameter is expected to be a string which indicates the SID of + the database. It is recommended to use ``service_name`` instead. + + The ``server_type`` parameter is expected to be a string that indicates the + type of server connection that should be established. If specified, it + should be one of *dedicated*, *shared*, or *pooled*. + + The ``cclass`` parameter is expected to be a string that identifies the + connection class to use for :ref:`drcp`. + + The ``purity`` parameter is expected to be one of the + :ref:`oracledb.PURITY_* ` constants that identifies the + purity to use for DRCP. The purity will internally default to + :data:`~oracledb.PURITY_SELF` for pooled connections. For standalone + connections, the purity will internally default to + :data:`~oracledb.PURITY_NEW`. + + The ``expire_time`` parameter is expected to be an integer which indicates + the number of minutes between the sending of keepalive probes. If this + parameter is set to a value greater than zero it enables keepalive. The + default value is *0*. + + The ``retry_count`` parameter is expected to be an integer that identifies + the number of times that a connection attempt should be retried before the + attempt is terminated. The default value is *0*. + + The ``retry_delay`` parameter is expected to be an integer that identifies + the number of seconds to wait before making a new connection attempt. The + default value is *1*. + + The ``tcp_connect_timeout`` parameter is expected to be a float that + indicates the maximum number of seconds to wait for establishing a + connection to the database host. The default value is *20.0*. + + The ``ssl_server_dn_match`` parameter is expected to be a boolean that + indicates whether the server certificate distinguished name (DN) should be + matched in addition to the regular certificate verification that is + performed. Note that if the ``ssl_server_cert_dn`` parameter is not + provided, host name matching is performed instead. The default value is + *True*. + + The ``ssl_server_cert_dn`` parameter is expected to be a string that + indicates the distinguished name (DN) which should be matched with the + server. This value is ignored if the ``ssl_server_dn_match`` parameter is + not set to the value *True*. + + The ``wallet_location`` parameter is expected to be a string that + identifies the directory where the wallet can be found. In python-oracledb + Thin mode, this must be the directory of the PEM-encoded wallet file, + ewallet.pem. + + The ``events`` parameter is ignored in the python-oracledb Thin mode. + + The ``externalauth`` parameter is ignored in the python-oracledb Thin mode. + + If the ``mode`` parameter is specified, it must be one of the + :ref:`connection authorization modes ` + which are defined at the module level. The default value is + :data:`oracledb.AUTH_MODE_DEFAULT`. + + The ``disable_oob`` parameter is expected to be a boolean that indicates + whether out-of-band breaks should be disabled. This value has no effect on + Windows which does not support this functionality. The default value is + *False*. + + The ``stmtcachesize`` parameter is expected to be an integer which + specifies the initial size of the statement cache. The default is the + value of :attr:`defaults.stmtcachesize`. + + The ``tag`` parameter is ignored in the python-oracledb Thin mode. + + The ``matchanytag`` parameter is ignored in the python-oracledb Thin mode. + + The ``config_dir`` parameter is expected to be a string that indicates the + directory in which :ref:`optional configuration files ` are + found. The default is the value of :attr:`defaults.config_dir`. + + The ``appcontext`` parameter is expected to be a list of 3-tuples that + identifies the application context used by the connection. This parameter + should contain namespace, name, and value and each entry in the tuple + should be a string. + + The ``shardingkey`` parameter and ``supershardingkey`` parameters are + ignored in the python-oracledb Thin mode. + + The ``debug_jdwp`` parameter is expected to be a string with the format + `host=;port=` that specifies the host and port of the PL/SQL + debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug + PL/SQL code called by python-oracledb. + + The ``connection_id_prefix`` parameter is expected to be a string and is + added to the beginning of the generated ``connection_id`` that is sent to + the database for `tracing `__. + + The ``ssl_context`` parameter is expected to be an SSLContext object used + for connecting to the database using TLS. This SSL context will be + modified to include the private key or any certificates found in a + separately supplied wallet. This parameter should only be specified if + the default SSLContext object cannot be used. + + The ``sdu`` parameter is expected to be an integer that returns the + requested size of the Session Data Unit (SDU), in bytes. The value tunes + internal buffers used for communication to the database. Bigger values can + increase throughput for large queries or bulk data loads, but at the cost + of higher memory use. The SDU size that will actually be used is negotiated + down to the lower of this value and the database network SDU configuration + value. See the `Database Net Services documentation `__ for more details. The default value is *8192* bytes. + + The ``pool_boundary`` parameter is expected to be one of the strings + *statement* or *transaction* which indicates when pooled :ref:`DRCP ` + or PRCP connections can be returned to the pool. If the value is + *statement*, then pooled DRCP or PRCP connections are implicitly released + back to the DRCP or PRCP pool when the connection is stateless (that is, + there are no active cursors, active transactions, temporary tables, or + temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP + connections are implicitly released back to the DRCP or PRCP pool when + either one of the methods :meth:`AsyncConnection.commit()` or + :meth:`AsyncConnection.rollback()` are called. This parameter requires the + use of DRCP or PRCP with Oracle Database 23ai (or later). See + :ref:`implicitconnpool` for more information. This value is used in both + the python-oracledb Thin and Thick modes. + + The ``use_tcp_fast_open`` parameter is expected to be a boolean which + indicates whether to use TCP Fast Open which is an `Oracle Autonomous + Database Serverless (ADB-S) `__ specific feature that can + reduce the latency in round-trips to the database after a connection has + been established. This feature is only available with certain versions of + ADB-S. This value is used in both python-oracledb Thin and Thick modes. + The default value is *False*. + + The ``ssl_version`` parameter is expected to be one of the constants + *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the + TLS protocol version used. These constants are defined in the Python + `ssl `__ module. This + parameter can be specified when establishing connections with the protocol + *tcps*. This value is used in both python-oracledb Thin and Thick modes. + The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you + are using python-oracledb Thick mode, Oracle Client 23ai is additionally + required. + + The ``use_sni`` parameter is expected to be a boolean which indicates + whether to use the TLS Server Name Indication (SNI) extension to bypass the + second TLS negotiation that would otherwise be required. This parameter is + used in both python-oracledb Thin and Thick modes. This parameter requires + Oracle Database 23.7. The default value is *False*. See the `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 + default is the value of :attr:`defaults.program`. + + The ``machine`` parameter is expected to be a string which specifies the + machine name of the client connecting to Oracle Database. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.machine`. + + The ``terminal`` parameter is expected to be a string which specifies the + terminal identifier from which the connection originates. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.terminal`. + + The ``osuser`` parameter is expected to be a string which specifies the + operating system user that initiates the database connection. This value + is only used in the python-oracledb Thin mode. The default value is the + value of :attr:`defaults.osuser`. + + The ``driver_name`` parameter is expected to be a string which specifies + the driver used by the client to connect to Oracle Database. This value + is used in both the python-oracledb Thin and Thick modes. The default is + the value of :attr:`defaults.driver_name`. + + The ``extra_auth_params`` parameter is expected to be a dictionary + containing the configuration parameters necessary for Oracle Database + authentication using :ref:`OCI ` or :ref:`Azure + ` cloud native authentication plugins. + This value is used in both the python-oracledb Thin and Thick modes. See + :ref:`tokenauth`. + + The ``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``, ``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 + + The ``program``, ``machine``, ``terminal``, ``osuser``, and + ``driver_name`` parameters were added. Support for ``edition`` and + ``appcontext`` was added. + + .. versionchanged:: 2.3.0 + + The default value of the ``retry_delay`` parameter was changed from 0 + seconds to 1 second. The default value of the ``tcp_connect_timeout`` + parameter was changed from 60.0 seconds to 20.0 seconds. The + ``ssl_version`` parameter was added. + + .. versionchanged:: 2.1.0 + + The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. + + .. versionchanged:: 2.0.0 + + The ``ssl_context`` and ``sdu`` parameters were added. + + .. versionchanged:: 1.4.0 + + The ``connection_id_prefix`` parameter was added. + +.. function:: ConnectParams(user=None, proxy_user=None, password=None, \ + newpassword=None, wallet_password=None, access_token=None, host=None, \ + port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, \ + service_name=None, instance_name=None, sid=None, server_type=None, \ + cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, \ + retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, \ + ssl_server_dn_match=True, ssl_server_cert_dn=None, \ + wallet_location=None, events=False, externalauth=False, \ + mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \ + stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, \ + tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, \ + appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ + connection_id_prefix=None, ssl_context=None, sdu=8192, \ + pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ + program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ + terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=0) + + Contains all the parameters that can be used to establish a connection to + the database. Creates and returns a :ref:`ConnectParams Object `. The object can be passed to :meth:`oracledb.connect()`. @@ -316,217 +845,391 @@ Oracledb Methods of the user to connect to. This value is used in both the python-oracledb Thin and :ref:`Thick ` modes. - The ``proxy_user`` parameter is expected to be a string which indicates the name of the - proxy user to connect to. If this value is not specified, it will be parsed out of - user if user is in the form "user[proxy_user]". This value is used in both the - python-oracledb Thin and Thick modes. + The ``proxy_user`` parameter is expected to be a string which indicates the + name of the proxy user to connect to. If this value is not specified, it + will be parsed out of user if user is in the form "user[proxy_user]". This + value is used in both the python-oracledb Thin and Thick modes. - The ``password`` parameter expected to be a string which indicates the password for - the user. This value is used in both the python-oracledb Thin and Thick modes. + The ``password`` parameter expected to be a string which indicates the + password for the user. This value is used in both the python-oracledb Thin + and Thick modes. - The ``newpassword`` parameter is expected to be a string which indicates the new - password for the user. The new password will take effect immediately upon a - successful connection to the database. This value is used in both the - python-oracledb Thin and Thick modes. + The ``newpassword`` parameter is expected to be a string which indicates + the new password for the user. The new password will take effect + immediately upon a successful connection to the database. This value is + used in both the python-oracledb Thin and Thick modes. - The ``wallet_password`` parameter is expected to be a string which indicates the - password to use to decrypt the PEM-encoded wallet, if it is encrypted. This - value is only used in python-oracledb Thin mode. The ``wallet_password`` parameter - is not needed for cwallet.sso files that are used in the python-oracledb Thick - mode. + The ``wallet_password`` parameter is expected to be a string which + indicates the password to use to decrypt the PEM-encoded wallet, if it is + encrypted. This value is only used in python-oracledb Thin mode. The + ``wallet_password`` parameter is not needed for cwallet.sso files that are + used in the python-oracledb Thick mode. The ``access_token`` parameter is expected to be a string or a 2-tuple or a callable. If it is a string, it specifies an Azure AD OAuth2 token used for Open Authorization (OAuth 2.0) token based authentication. If it is a 2-tuple, it specifies the token and private key strings used for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based - authentication. If it is a callable, it returns either a string or a 2-tuple - used for OAuth 2.0 or OCI IAM token based authentication and is useful when - the pool needs to expand and create new connections but the current - authentication token has expired. This value is used in both the + authentication. If it is a callable, it returns either a string or a + 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is + useful when the pool needs to expand and create new connections but the + current authentication token has expired. This value is used in both the python-oracledb Thin and Thick modes. - The ``host`` parameter is expected to be a string which specifies the name or IP - address of the machine hosting the listener, which handles the initial - connection to the database. This value is used in both the python-oracledb - Thin and Thick modes. - - The ``port`` parameter is expected to be an integer which indicates the port number - on which the listener is listening. The default value is 1521. This value is used - in both the python-oracledb Thin and Thick modes. - - The ``protocol`` parameter is expected to be one of the strings "tcp" or "tcps" - which indicates whether to use unencrypted network traffic or encrypted network - traffic (TLS). The default value is tcp. This value is used in both the + The ``host`` parameter is expected to be a string which specifies the name + or IP address of the machine hosting the listener, which handles the + initial connection to the database. This value is used in both the python-oracledb Thin and Thick modes. - The ``https_proxy`` parameter is expected to be a string which indicates the name or - IP address of a proxy host to use for tunneling secure connections. This value - is used in both the python-oracledb Thin and Thick modes. + The ``port`` parameter is expected to be an integer which indicates the + port number on which the listener is listening. The default value is + *1521*. This value is used in both the python-oracledb Thin and Thick + modes. - The ``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 ``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 ``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 + The ``https_proxy`` parameter is expected to be a string which indicates + the name or IP address of a proxy host to use for tunneling secure + connections. This value is used in both the python-oracledb Thin and Thick modes. - The ``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 ``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 ``server_type`` parameter is expected to be a string that indicates the type of - server connection that should be established. If specified, it should be one of - "dedicated", "shared", or "pooled". This value is used in both the + 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 ``cclass`` parameter is expected to be a string that identifies the connection - class to use for Database Resident Connection Pooling (DRCP). 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 ``purity`` parameter is expected to be one of the :ref:`oracledb.PURITY_* - ` constants that identifies the purity to use for - DRCP. This value is used in both the python-oracledb Thin and Thick modes. - The purity will internally default to :data:`~oracledb.PURITY_SELF` for pooled - connections . For standalone connections, the purity will internally default - to :data:`~oracledb.PURITY_NEW`. + The ``sid`` parameter is expected to be a string which indicates the SID of + the database. It is recommended to use ``service_name`` instead. This value + is used in both the python-oracledb Thin and Thick modes. + + The ``server_type`` parameter is expected to be a string that indicates the + type of server connection that should be established. If specified, it + should be one of *dedicated*, *shared*, or *pooled*. This value is used in + both the python-oracledb Thin and Thick modes. + + The ``cclass`` parameter is expected to be a string that identifies the + connection class to use for :ref:`drcp`. This value is used in both the + python-oracledb Thin and Thick modes. - The ``expire_time`` parameter is expected to be an integer which indicates the - number of minutes between the sending of keepalive probes. If this parameter - is set to a value greater than zero it enables keepalive. This value is used - in both the python-oracledb Thin and Thick modes. The default value is 0. + The ``purity`` parameter is expected to be one of the + :ref:`oracledb.PURITY_* ` constants that identifies the + purity to use for DRCP. This value is used in both the python-oracledb Thin + and Thick modes. The purity will internally default to + :data:`~oracledb.PURITY_SELF` for pooled connections . For standalone + connections, the purity will internally default to + :data:`~oracledb.PURITY_NEW`. + + The ``expire_time`` parameter is expected to be an integer which indicates + the number of minutes between the sending of keepalive probes. If this + parameter is set to a value greater than zero it enables keepalive. This + value is used in both the python-oracledb Thin and Thick modes. The default + value is *0*. - The ``retry_count`` parameter is expected to be an integer that identifies the - number of times that a connection attempt should be retried before the + 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 + 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 0. - - 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 60.0. - - The ``ssl_server_dn_match`` parameter is expected to be a boolean that indicates - whether the server certificate distinguished name (DN) should be matched in - addition to the regular certificate verification that is performed. Note that - if the ``ssl_server_cert_dn`` parameter is not provided, host name matching - is performed instead. This value is used in both the python-oracledb Thin and - Thick modes. The default value is True. - - The ``ssl_server_cert_dn`` parameter is expected to be a string that indicates - the distinguished name (DN) which should be matched with the server. This - value is ignored if the ``ssl_server_dn_match`` parameter is not set to the - value True. This value is used in both the python-oracledb Thin and Thick - modes. + value is *1*. - The ``wallet_location`` parameter is expected to be a string that identifies - the directory where the wallet can be found. In python-oracledb Thin mode, - this must be the directory of the PEM-encoded wallet file, ewallet.pem. - In python-oracledb Thick mode, this must be the directory of the file, - cwallet.sso. This value is used in both the python-oracledb Thin and Thick - modes. + The ``tcp_connect_timeout`` parameter is expected to be a float that + indicates the maximum number of seconds to wait for establishing a + connection to the database host. This value is used in both the + python-oracledb Thin and Thick modes. The default value is *20.0*. + + The ``ssl_server_dn_match`` parameter is expected to be a boolean that + indicates whether the server certificate distinguished name (DN) should be + matched in addition to the regular certificate verification that is + performed. Note that if the ``ssl_server_cert_dn`` parameter is not + provided, host name matching is performed instead. This value is used in + both the python-oracledb Thin and Thick modes. The default value is *True*. + + The ``ssl_server_cert_dn`` parameter is expected to be a string that + indicates the distinguished name (DN) which should be matched with the + server. This value is ignored if the ``ssl_server_dn_match`` parameter is + not set to the value *True*. This value is used in both the python-oracledb + Thin and Thick modes. + + The ``wallet_location`` parameter is expected to be a string that + identifies the directory where the wallet can be found. In python-oracledb + Thin mode, this must be the directory of the PEM-encoded wallet file, + ewallet.pem. In python-oracledb Thick mode, this must be the directory of + the file, cwallet.sso. This value is used in both the python-oracledb Thin + and Thick modes. The ``events`` parameter is expected to be a boolean that specifies whether the events mode should be enabled. This value is only used in the python-oracledb Thick mode. This parameter is needed for continuous query notification and high availability event notifications. The default - value is False. + value is *False*. The ``externalauth`` parameter is a boolean that specifies whether external - authentication should be used. This value is only used in the python-oracledb - Thick mode. The default value is False. For standalone connections, - external authentication occurs when the ``user`` and ``password`` attributes - are not used. If these attributes are not used, you can optionally set the - ``externalauth`` attribute to True, which may aid code auditing. + authentication should be used. This value is only used in the + python-oracledb Thick mode. The default value is *False*. For standalone + connections, external authentication occurs when the ``user`` and + ``password`` attributes are not used. If these attributes are not used, you + can optionally set the ``externalauth`` attribute to *True*, which may aid + code auditing. The ``mode`` parameter is expected to be an integer that identifies the authorization mode to use. This value is used in both the python-oracledb - Thin and Thick modes.The default value is :data:`oracledb.AUTH_MODE_DEFAULT`. + Thin and Thick modes.The default value is + :data:`oracledb.AUTH_MODE_DEFAULT`. The ``disable_oob`` parameter is expected to be a boolean that indicates whether out-of-band breaks should be disabled. This value is only used in the python-oracledb Thin mode and has no effect on Windows which - does not support this functionality. The default value is False. + does not support this functionality. The default value is *False*. - The ``stmtcachesize`` parameter is expected to be an integer that identifies - the initial size of the statement cache. This value is used in both the - python-oracledb Thin and Thick modes. The default is the value of + The ``stmtcachesize`` parameter is expected to be an integer that + identifies the initial size of the statement cache. This value is used in + both the python-oracledb Thin and Thick modes. The default is the value of :attr:`defaults.stmtcachesize`. The ``edition`` parameter is expected to be a string that indicates the - edition to use for the connection. This parameter cannot be used - simultaneously with the ``cclass`` parameter. This value is used in the - python-oracledb Thick mode. + edition to use for the connection. It requires Oracle Database 11.2, or + later. This parameter cannot be used simultaneously with the ``cclass`` + parameter. The ``tag`` parameter is expected to be a string that identifies the type of connection that should be returned from a pool. This value is only used in the python-oracledb Thick mode. - The ``matchanytag`` parameter is expected to be a boolean specifying whether - any tag can be used when acquiring a connection from the pool. This value - is only used in the python-oracledb Thick mode when acquiring a connection - from a pool. The default value is False. + The ``matchanytag`` parameter is expected to be a boolean specifying + whether any tag can be used when acquiring a connection from the pool. This + value is only used in the python-oracledb Thick mode when acquiring a + connection from a pool. The default value is *False*. The ``config_dir`` parameter is expected to be a string that indicates the - directory in which 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()`. - - The ``appcontext`` parameter is expected to be a list of 3-tuples that identifies - the application context used by the connection. This parameter should contain - namespace, name, and value and each entry in the tuple should be a string. - This value is only used inthe python-oracledb Thick mode. - - The ``shardingkey`` parameter is expected to be a list of strings, numbers, bytes - or dates that identifies the database shard to connect to. This value is only - used in the python-oracledb Thick mode. + directory in which the :ref:`tnsnames.ora ` configuration file + is located. + + The ``appcontext`` parameter is expected to be a list of 3-tuples that + identifies the application context used by the connection. This parameter + should contain namespace, name, and value and each entry in the tuple + should be a string. - The ``supershardingkey`` parameter is expected to be a list of strings, numbers, - bytes or dates that identifies the database shard to connect to. This value is - only used in the python-oracledb Thick mode. + The ``shardingkey`` parameter and ``supershardingkey`` parameters, if + specified, are expected to be a sequence of values which identifies the + database shard to connect to. The key values can be a list of strings, + numbers, bytes, or dates. These values are only used in the + python-oracledb Thick mode and are ignored in the Thin mode. See + :ref:`connsharding`. The ``debug_jdwp`` parameter is expected to be a string with the format - `host=;port=` that specifies the host and port of the PL/SQL debugger. - This allows using the Java Debug Wire Protocol (JDWP) to debug PL/SQL code invoked - by python-oracledb. This value is only used in the python-oracledb Thin mode. - For python-oracledb Thick mode, set the ``ORA_DEBUG_JDWP`` environment variable - which has the same syntax. For more information, see :ref:`applntracing`. + `host=;port=` that specifies the host and port of the PL/SQL + debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug + PL/SQL code invoked by python-oracledb. This value is only used in the + python-oracledb Thin mode. For python-oracledb Thick mode, set the + ``ORA_DEBUG_JDWP`` environment variable which has the same syntax. For more + information, see :ref:`applntracing`. + + The ``connection_id_prefix`` parameter is expected to be a string and is + added to the beginning of the generated ``connection_id`` that is sent to + the database for `tracing `__. This value + is only used in the python-oracledb Thin mode. + + The ``ssl_context`` parameter is expected to be an `SSLContext object + `__ which is used + for connecting to the database using TLS. This SSL context will be + modified to include the private key or any certificates found in a + separately supplied wallet. This parameter should only be specified if + the default SSLContext object cannot be used. This value is only used in + the python-oracledb Thin mode. + + The ``sdu`` parameter is expected to be an integer that returns the + requested size of the Session Data Unit (SDU), in bytes. The value tunes + internal buffers used for communication to the database. Bigger values can + increase throughput for large queries or bulk data loads, but at the cost + of higher memory use. The SDU size that will actually be used is negotiated + down to the lower of this value and the database network SDU configuration + value. See the `Database Net Services documentation `__ for more details. This value is used in both the + python-oracledb Thin and Thick modes. The default value is *8192* bytes. + + The ``pool_boundary`` parameter is expected to be one of the strings + *statement* or *transaction* which indicates when pooled :ref:`DRCP ` + or PRCP connections can be returned to the pool. If the value is + *statement*, then pooled DRCP or PRCP connections are implicitly released + back to the DRCP or PRCP pool when the connection is stateless (that is, + there are no active cursors, active transactions, temporary tables, or + temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP + connections are implicitly released back to the DRCP or PRCP pool when + either one of the methods :meth:`Connection.commit()` or + :meth:`Connection.rollback()` are called. This parameter requires the use + of DRCP or PRCP with Oracle Database 23ai (or later). See + :ref:`implicitconnpool` for more information. This value is used in both + the python-oracledb Thin and Thick modes. + + The ``use_tcp_fast_open`` parameter is expected to be a boolean which + indicates whether to use TCP Fast Open which is an `Oracle Autonomous + Database Serverless (ADB-S) `__ specific feature that can + reduce the latency in round-trips to the database after a connection has + been established. This feature is only available with certain versions of + ADB-S. This value is used in both python-oracledb Thin and Thick modes. + The default value is *False*. + + The ``ssl_version`` parameter is expected to be one of the constants + *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the + TLS protocol version used. These constants are defined in the Python + `ssl `__ module. This + parameter can be specified when establishing connections with the protocol + "tcps". This value is used in both python-oracledb Thin and Thick modes. + The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you + are using python-oracledb Thick mode, Oracle Client 23ai is additionally + required. + + The ``use_sni`` parameter is expected to be a boolean which indicates + whether to use the TLS Server Name Indication (SNI) extension to bypass the + second TLS negotiation that would otherwise be required. This parameter is + used in both python-oracledb Thin and Thick modes. This parameter requires + Oracle Database 23.7. The default value is *False*. See the `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 + default is the value of :attr:`defaults.program`. + + The ``machine`` parameter is expected to be a string which specifies the + machine name of the client connecting to Oracle Database. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.machine`. + + The ``terminal`` parameter is expected to be a string which specifies the + terminal identifier from which the connection originates. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.terminal`. + + The ``osuser`` parameter is expected to be a string which specifies the + operating system user that initiates the database connection. This value + is only used in the python-oracledb Thin mode. The default value is the + value of :attr:`defaults.osuser`. + + The ``driver_name`` parameter is expected to be a string which specifies + the driver used by the client to connect to Oracle Database. This value + is used in both the python-oracledb Thin and Thick modes. The default is + the value of :attr:`defaults.driver_name`. + + The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean + which indicates whether the connect string should be passed unchanged to + the Oracle Client libraries for parsing when using python-oracledb Thick + mode. If this parameter is set to *False* in Thick mode, connect strings + are parsed by python-oracledb itself and a generated connect descriptor is + sent to the Oracle Client libraries. This value is only used in the + python-oracledb Thick mode. The default value is the value of + :attr:`defaults.thick_mode_dsn_passthrough`. For more information, see + :ref:`usingconfigfiles`. + + The ``extra_auth_params`` parameter is expected to be a dictionary + containing the configuration parameters necessary for Oracle Database + authentication using :ref:`OCI ` or :ref:`Azure + ` cloud native authentication plugins. This value is + used in both the python-oracledb Thin and Thick modes. See + :ref:`tokenauth`. + + The ``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 + + The ``program``, ``machine``, ``terminal``, ``osuser``, and + ``driver_name`` parameters were added. Support for ``edition`` and + ``appcontext`` was added to python-oracledb Thin mode. + + .. versionchanged:: 2.3.0 + + The default value of the ``retry_delay`` parameter was changed from 0 + seconds to 1 second. The default value of the ``tcp_connect_timeout`` + parameter was changed from 60.0 seconds to 20.0 seconds. The + ``ssl_version`` parameter was added. + + .. versionchanged:: 2.1.0 + + The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. + + .. versionchanged:: 2.0.0 + + The ``ssl_context`` and ``sdu`` parameters were added. + + .. versionchanged:: 1.4.0 + + The ``connection_id_prefix`` parameter was added. + +.. function:: create_pipeline() + Creates a :ref:`pipeline object ` which can be used to + process a set of operations against a database. + + .. versionadded:: 2.4.0 .. function:: create_pool(dsn=None, pool_class=oracledb.ConnectionPool, \ - params=None, min=1, max=2, increment=1, connectiontype=oracledb.Connection, \ + pool_alias=None, params=None, min=1, max=2, increment=1, \ + connectiontype=oracledb.Connection, \ getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, timeout=0, \ wait_timeout=0, max_lifetime_session=0, session_callback=None, \ max_sessions_per_shard=0, soda_metadata_cache=False, ping_interval=60, \ - 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=0, tcp_connect_timeout=60.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, \ + ping_timeout=5000, user=None, proxy_user=None, password=None, \ + newpassword=None, wallet_password=None, access_token=None, host=None, \ + port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, \ + service_name=None, instance_name=None, sid=None, server_type=None, \ + cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, \ + retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, \ + ssl_server_dn_match=True, ssl_server_cert_dn=None, \ + wallet_location=None, events=False, externalauth=False, \ + mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \ + stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, \ tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, \ - appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, handle=0) + appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ + connection_id_prefix=None, ssl_context=None, sdu=8192, \ + pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ + program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ + terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, 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 pooling ` for more information. - This function is the equivalent of the `cx_Oracle.SessionPool() - `__ + This function is the equivalent of the ``cx_Oracle.SessionPool()`` function. The use of ``SessionPool()`` has been deprecated in python-oracledb. @@ -546,12 +1249,32 @@ Oracledb Methods ``params`` parameter object. Similar precedence rules also apply to other values. + Python-oracledb connection pools must be created, used and closed within + the same process. Sharing pools or connections across processes has + unpredictable behavior. Using connection pools in multi-threaded + architectures is supported. Multi-process architectures that cannot be + converted to threading may get some benefit from :ref:`drcp`. + + In python-oracledb Thick mode, connection pooling is handled by Oracle's + `Session pooling `__ technology. + This allows python-oracledb applications to support features like + `Application Continuity `__. + The ``user``, ``password``, and ``dsn`` parameters are the same as for :meth:`oracledb.connect()`. The ``pool_class`` parameter is expected to be a :ref:`ConnectionPool Object ` or a subclass of ConnectionPool. + The ``pool_alias`` parameter is expected to be a string representing the + name used to store and reference the pool in the python-oracledb connection + pool cache. If this parameter is not specified, then the pool will not be + added to the cache. The value of this parameter can be used with the + :meth:`oracledb.get_pool()` and :meth:`oracledb.connect()` methods to + access the pool. See :ref:`connpoolcache`. + The ``params`` parameter is expected to be of type :ref:`PoolParams ` and contains parameters that are used to create the pool. If this parameter is not specified, the additional keyword parameters will @@ -568,11 +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 connections - that are opened whenever a connection request exceeds the number of currently - open connections. The default value of the ``increment`` parameter is 1. - The ``max`` parameter is the maximum number of connections that can be open - in the connection pool. The default value of the ``max`` parameter is 2. + ``min`` parameter is *1*. The ``increment`` parameter is the number of + connections that are opened whenever a connection request exceeds the + number of currently open connections. The default value of the + ``increment`` parameter is *1*. The ``max`` parameter is the maximum number + of connections that can be open in the connection pool. The default value + of the ``max`` parameter is *2*. If the ``connectiontype`` parameter is specified, all calls to :meth:`ConnectionPool.acquire()` will create connection objects of that @@ -587,34 +1311,41 @@ 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. If the - value of this parameter is 0, then the connections are never terminated. - The default value is 0. + connection may remain idle in the pool before it is terminated. This + applies only when the pool has more than ``min`` connections open, allowing + it to shrink to the specified minimum size. The default value is *0* + seconds. A value of *0* means there is no limit. The ``wait_timeout`` parameter is the length of time (in milliseconds) that a caller should wait when acquiring a connection from the pool with ``getmode`` set to :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default - value is 0. + 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 connection tag differs from the one requested. The ``max_sessions_per_shard`` parameter is the maximum number of - connections that may be associated with a particular shard. The default - value is 0. + connections that may be associated with a particular shard. This value is + only used in the python-oracledb Thick mode and is ignored in the + python-oracledb Thin mode. The default value is *0*. The ``soda_metadata_cache`` parameter is a boolean that indicates whether - or not the SODA metadata cache should be enabled. The default value is - False. + or not the SODA metadata cache should be enabled. This value is only used + in the python-oracledb Thick mode and is ignored in the python-oracledb + Thin mode. The default value is *False*. The ``ping_interval`` parameter is the length of time (in seconds) after which an unused connection in the pool will be a candidate for pinging when @@ -622,7 +1353,15 @@ 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 + to respond to any internal ping to the database. If the ping does not + respond within the specified time, then the connection is destroyed and + :meth:`~ConnectionPool.acquire()` returns a different connection. This + value is used in both the python-oracledb Thin and Thick modes. The default + value is *5000* milliseconds. The ``proxy_user`` parameter is expected to be a string which indicates the name of the proxy user to connect to. If this value is not specified, it @@ -645,10 +1384,10 @@ Oracledb Methods for Open Authorization (OAuth 2.0) token based authentication. If it is a 2-tuple, it specifies the token and private key strings used for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based - authentication. If it is a callable, it returns either a string or a 2-tuple - used for OAuth 2.0 or OCI IAM token based authentication and is useful when - the pool needs to expand and create new connections but the current - authentication token has expired. This value is used in both the + authentication. If it is a callable, it returns either a string or a + 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is + useful when the pool needs to expand and create new connections but the + current authentication token has expired. This value is used in both the python-oracledb Thin and Thick modes. The ``host`` parameter is expected to be a string which specifies the name @@ -657,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 @@ -672,25 +1412,29 @@ 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 - connection class to use for Database Resident Connection Pooling (DRCP). - This value is used in both the python-oracledb Thin and Thick modes. + connection class to use for :ref:`drcp`. This value is used in both the + python-oracledb Thin and Thick modes. The ``purity`` parameter is expected to be one of the :ref:`oracledb.PURITY_* ` constants that identifies the @@ -702,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 0. + 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 60.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 @@ -741,13 +1485,16 @@ Oracledb Methods 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. + python-oracledb Thick mode and is ignored in the Thin mode. This parameter + is needed for continuous query notification and high availability event + notifications. The default value is *False*. The ``externalauth`` parameter is a boolean that determines whether to use - external authentication. This value is only used in the python-oracledb Thick - mode. The default value is False. + external authentication. This value is only used in python-oracledb Thick + mode and is ignored in Thin mode. The default value is *False*. For pooled + connections in Thick mode, external authentication requires the use of a + heterogeneous pool. For this reason, you must set the ``homogeneous`` + parameter to *False*. See :ref:`extauth`. If the ``mode`` parameter is specified, it must be one of the :ref:`connection authorization modes ` @@ -758,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 @@ -766,36 +1513,35 @@ Oracledb Methods :attr:`defaults.stmtcachesize`. The ``edition`` parameter is expected to be a string that indicates the - edition to use for the connection. This parameter cannot be used - simultaneously with the ``cclass`` parameter. This value is used in the - python-oracledb Thick mode. + edition to use for the connection. It requires Oracle Database 11.2, or + later. This parameter cannot be used simultaneously with the ``cclass`` + parameter. The ``tag`` parameter is expected to be a string that identifies the type of connection that should be returned from a pool. This value is only used - in the python-oracledb Thick mode. + in the python-oracledb Thick mode and is ignored in the Thin mode. The ``matchanytag`` parameter is expected to be a boolean specifying whether any tag can be used when acquiring a connection from the pool. This value is only used in the python-oracledb Thick mode when acquiring a - connection from a pool. The default value is False. + connection from a pool. This value is ignored in the python-oracledb Thin + mode. The default value is *False*. The ``config_dir`` parameter is expected to be a string that indicates the - directory in which 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 should contain namespace, name, and value and each entry in the tuple - should be a string. This value is only used inthe python-oracledb Thick - mode. + should be a string. The ``shardingkey`` parameter and ``supershardingkey`` parameters, if specified, are expected to be a sequence of values which identifies the database shard to connect to. The key values can be a list of strings, - numbers, bytes, or dates. This value is only used in the python-oracledb - Thick mode. + numbers, bytes, or dates. These values are only used in the + python-oracledb Thick mode and are ignored in the Thin mode. See + :ref:`connsharding`. The ``debug_jdwp`` parameter is expected to be a string with the format `host=;port=` that specifies the host and port of the PL/SQL @@ -805,30 +1551,587 @@ Oracledb Methods ``ORA_DEBUG_JDWP`` environment variable which has the same syntax. For more information, see :ref:`applntracing`. + The ``connection_id_prefix`` parameter is expected to be a string and is + added to the beginning of the generated ``connection_id`` that is sent to + the database for `tracing `__. This value + is only used in the python-oracledb Thin mode. + + The ``ssl_context`` parameter is expected to be an `SSLContext object + `__ which is used + for connecting to the database using TLS. This SSL context will be + modified to include the private key or any certificates found in a + separately supplied wallet. This parameter should only be specified if + the default SSLContext object cannot be used. This value is only used in + the python-oracledb Thin mode. + + The ``sdu`` parameter is expected to be an integer that returns the + requested size of the Session Data Unit (SDU), in bytes. The value tunes + internal buffers used for communication to the database. Bigger values can + increase throughput for large queries or bulk data loads, but at the cost + of higher memory use. The SDU size that will actually be used is negotiated + down to the lower of this value and the database network SDU configuration + value. See the `Database Net Services documentation `__ for more details. This value is used in both the + python-oracledb Thin and Thick modes. The default value is *8192* bytes. + + The ``pool_boundary`` parameter is expected to be one of the strings + *statement* or *transaction* which indicates when pooled :ref:`DRCP ` + or PRCP connections can be returned to the pool. If the value is + *statement*, then pooled DRCP or PRCP connections are implicitly released + back to the DRCP or PRCP pool when the connection is stateless (that is, + there are no active cursors, active transactions, temporary tables, or + temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP + connections are implicitly released back to the DRCP or PRCP pool when + either one of the methods :meth:`Connection.commit()` or + :meth:`Connection.rollback()` are called. This parameter requires the use + of DRCP or PRCP with Oracle Database 23ai (or later). See + :ref:`implicitconnpool` for more information. This value is used in both + the python-oracledb Thin and Thick modes. + + The ``use_tcp_fast_open`` parameter is expected to be a boolean which + indicates whether to use TCP Fast Open which is an `Oracle Autonomous + Database Serverless (ADB-S) `__ specific feature that can + reduce the latency in round-trips to the database after a connection has + been established. This feature is only available with certain versions of + ADB-S. This value is used in both python-oracledb Thin and Thick modes. + The default value is *False*. + + The ``ssl_version`` parameter is expected to be one of the constants + *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the + TLS protocol version used. These constants are defined in the Python + `ssl `__ module. This + parameter can be specified when establishing connections with the protocol + "tcps". This value is used in both python-oracledb Thin and Thick modes. + The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you + are using python-oracledb Thick mode, Oracle Client 23ai is additionally + required. + + The ``use_sni`` parameter is expected to be a boolean which indicates + whether to use the TLS Server Name Indication (SNI) extension to bypass the + second TLS negotiation that would otherwise be required. This parameter is + used in both python-oracledb Thin and Thick modes. This parameter requires + Oracle Database 23.7. The default value is *False*. See the `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 + default is the value of :attr:`defaults.program`. + + The ``machine`` parameter is expected to be a string which specifies the + machine name of the client connecting to Oracle Database. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.machine`. + + The ``terminal`` parameter is expected to be a string which specifies the + terminal identifier from which the connection originates. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.terminal`. + + The ``osuser`` parameter is expected to be a string which specifies the + operating system user that initiates the database connection. This value + is only used in the python-oracledb Thin mode. The default value is the + value of :attr:`defaults.osuser`. + + The ``driver_name`` parameter is expected to be a string which specifies + the driver used by the client to connect to Oracle Database. This value + is used in both the python-oracledb Thin and Thick modes. The default is + the value of :attr:`defaults.driver_name`. + + The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean + which indicates whether the connect string should be passed unchanged to + the Oracle Client libraries for parsing when using python-oracledb Thick + mode. If this parameter is set to *False* in Thick mode, connect strings + are parsed by python-oracledb itself and a generated connect descriptor is + sent to the Oracle Client libraries. This value is only used in the + python-oracledb Thick mode. The default value is + :attr:`defaults.thick_mode_dsn_passthrough`. For more information, see + :ref:`usingconfigfiles`. + + The ``extra_auth_params`` parameter is expected to be a dictionary + containing the configuration parameters necessary for Oracle Database + authentication using :ref:`OCI ` or :ref:`Azure + ` cloud native authentication plugins. This value is + used in both the python-oracledb Thin and Thick modes. See + :ref:`tokenauth`. + + 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. It - should be used with extreme caution. The deault value is 0. + 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*. - In the python-oracledb Thick mode, connection pooling is handled by - Oracle's `Session pooling `__ technology. - This allows python-oracledb applications to support features like - `Application Continuity `__. + .. versionchanged:: 3.2.0 + The ``pool_name`` parameter was added. -.. function:: Cursor(connection) + .. versionchanged:: 3.0.0 - Constructor for creating a cursor. Returns a new - :ref:`cursor object ` using the connection. + The ``pool_alias``, ``instance_name``, ``use_sni``, + ``thick_mode_dsn_passthrough``, and ``extra_auth_params`` parameters + were added. - .. note:: + .. versionchanged:: 2.5.0 + + The ``program``, ``machine``, ``terminal``, ``osuser``, and + ``driver_name`` parameters were added. Support for ``edition`` and + ``appcontext`` was added to python-oracledb Thin mode. + + .. versionchanged:: 2.3.0 + + The default value of the ``retry_delay`` parameter was changed from *0* + seconds to *1* second. The default value of the ``tcp_connect_timeout`` + parameter was changed from *60.0* seconds to *20.0* seconds. The + ``ping_timeout`` and ``ssl_version`` parameters were added. + + .. versionchanged:: 2.1.0 + + The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. + + .. versionchanged:: 2.0.0 + + The ``ssl_context`` and ``sdu`` parameters were added. + + .. versionchanged:: 1.4.0 + + The ``connection_id_prefix`` parameter was added. + +.. function:: create_pool_async(dsn=None, \ + pool_class=oracledb.AsyncConnectionPool, pool_alias=None, \ + params=None, min=1, max=2, increment=1, \ + connectiontype=oracledb.AsyncConnection, \ + getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, timeout=0, \ + wait_timeout=0, max_lifetime_session=0, session_callback=None, \ + max_sessions_per_shard=0, soda_metadata_cache=False, ping_interval=60, \ + ping_timeout=5000, user=None, proxy_user=None, password=None, \ + newpassword=None, wallet_password=None, access_token=None, host=None, \ + port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, \ + service_name=None, instance_name=None, sid=None, server_type=None, \ + cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, \ + retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, \ + ssl_server_dn_match=True, ssl_server_cert_dn=None, \ + wallet_location=None, events=False, externalauth=False, \ + mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \ + stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, \ + tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, \ + appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ + connection_id_prefix=None, ssl_context=None, sdu=8192, \ + pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ + program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ + terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=0) + + Creates a connection pool with the supplied parameters and returns the + :ref:`AsyncConnectionPool object ` for the pool. + ``create_pool_async()`` is a synchronous method. See + :ref:`Connection pooling ` for more information. + + This method can only be used in python-oracledb Thin mode. + + When connecting to Oracle Autonomous Database, use Python 3.11, or later. + + .. versionadded:: 2.0.0 + + Some values, such as the database host name, can be specified as + parameters, as part of the connect string, and in the params object. + The precedence is that values in the ``dsn`` parameter override values + passed as individual parameters, which themselves override values set in + the ``params`` parameter object. Similar precedence rules also apply to + other values. + + The ``user``, ``password``, and ``dsn`` parameters are the same as for + :meth:`oracledb.connect()`. + + The ``pool_class`` parameter is expected to be an + :ref:`AsyncConnectionPool Object ` or a subclass of + AsyncConnectionPool. + + The ``pool_alias`` parameter is expected to be a string representing the + name used to store and reference the pool in the python-oracledb connection + pool cache. If this parameter is not specified, then the pool will not be + added to the cache. The value of this parameter can be used with the + :meth:`oracledb.get_pool()` and :meth:`oracledb.connect_async()` methods to + access the pool. See :ref:`connpoolcache`. + + The ``params`` parameter is expected to be of type :ref:`PoolParams + ` and contains parameters that are used to create the pool. + If this parameter is not specified, the additional keyword parameters will + be used to create an instance of PoolParams. If both the params parameter + and additional keyword parameters are specified, the values in the keyword + parameters have precedence. Note that if a ``dsn`` is also supplied, then + the values of the parameters specified (if any) within the ``dsn`` will + override the values passed as additional keyword parameters, which + themselves override the values set in the ``params`` parameter object. - This method is an extension to the DB API definition. + The ``min``, ``max`` and ``increment`` parameters control pool growth + behavior. A fixed pool size where ``min`` equals ``max`` is + :ref:`recommended ` to help prevent connection storms and to + help overall system stability. The ``min`` parameter is the number of + connections opened when the pool is created. The default value of the + ``min`` parameter is *1*. The ``increment`` parameter is the number of + connections that are opened whenever a connection request exceeds the + number of currently open connections. The default value of the + ``increment`` parameter is *1*. The ``max`` parameter is the maximum number + of connections that can be open in the connection pool. The default value + of the ``max`` parameter is *2*. + + If the ``connectiontype`` parameter is specified, all calls to + :meth:`AsyncConnectionPool.acquire()` will create connection objects of + that type, rather than the base type defined at the module level. + + The ``getmode`` parameter determines the behavior of + :meth:`AsyncConnectionPool.acquire()`. One of the constants + :data:`oracledb.POOL_GETMODE_WAIT`, :data:`oracledb.POOL_GETMODE_NOWAIT`, + :data:`oracledb.POOL_GETMODE_FORCEGET`, or + :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default value is + :data:`oracledb.POOL_GETMODE_WAIT`. + + The ``homogeneous`` parameter is a boolean that indicates whether the + connections are homogeneous (same user) or heterogeneous (multiple + users). The default value is *True*. + + The ``timeout`` parameter is the length of time (in seconds) that a + connection may remain idle in the pool before it is terminated. This + applies only when the pool has more than ``min`` connections open, allowing + it to shrink to the specified minimum size. The default value is *0* + seconds. A value of *0* means there is no limit. + + The ``wait_timeout`` parameter is the length of time (in milliseconds) that + a caller should wait when acquiring a connection from the pool with + ``getmode`` set to :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default + value is *0* milliseconds. + + The ``max_lifetime_session`` parameter is the length of time (in seconds) + that a pooled connection may exist since first being created. The default + value is *0*. A value of *0* means that there is no limit. Connections + become candidates for termination when they are acquired or released back + to the pool and have existed for longer than ``max_lifetime_session`` + seconds. In python-oracledb Thick mode, Oracle Client libraries 12.1 or + later must be used and, prior to Oracle Client 21, cleanup only occurs when + the pool is accessed. + + The ``session_callback`` parameter is a callable that is invoked when a + connection is returned from the pool for the first time, or when the + connection tag differs from the one requested. + + The ``max_sessions_per_shard`` parameter is ignored in the python-oracledb + Thin mode. + + The ``soda_metadata_cache`` parameter is ignored in the python-oracledb + Thin mode. + + The ``ping_interval`` parameter is the length of time (in seconds) after + which an unused connection in the pool will be a candidate for pinging when + :meth:`AsyncConnectionPool.acquire()` is called. If the ping to the + database indicates the connection is not alive a replacement connection + will be returned by :meth:`~AsyncConnectionPool.acquire()`. If + ``ping_interval`` is a negative value, then the ping functionality will be + disabled. The default value is *60* seconds. + + The ``ping_timeout`` parameter is the maximum length of time (in + milliseconds) that :meth:`AsyncConnectionPool.acquire()` waits for a + connection to respond to any internal ping to the database. If the ping + does not respond within the specified time, then the connection is + destroyed and :meth:`~AsyncConnectionPool.acquire()` returns a different + connection. This value is used in both the python-oracledb Thin and Thick + modes. The default value is *5000* milliseconds. + + The ``proxy_user`` parameter is expected to be a string which indicates the + name of the proxy user to connect to. If this value is not specified, it + will be parsed out of user if user is in the form "user[proxy_user]". + + The ``newpassword`` parameter is expected to be a string which indicates + the new password for the user. The new password will take effect + immediately upon a successful connection to the database. + + The ``wallet_password`` parameter is expected to be a string which + indicates the password to use to decrypt the PEM-encoded wallet, if it is + encrypted. + + The ``access_token`` parameter is expected to be a string or a 2-tuple or + a callable. If it is a string, it specifies an Azure AD OAuth2 token used + for Open Authorization (OAuth 2.0) token based authentication. If it is a + 2-tuple, it specifies the token and private key strings used for Oracle + Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based + authentication. If it is a callable, it returns either a string or a + 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is + useful when the pool needs to expand and create new connections but the + current authentication token has expired. + + The ``host`` parameter is expected to be a string which specifies the name + or IP address of the machine hosting the listener, which handles the + initial connection to the database. + + The ``port`` parameter is expected to be an integer which indicates the + port number on which the listener is listening. The default value is + *1521*. + + The ``protocol`` parameter is expected to be one of the strings *tcp* or + *tcps* which indicates whether to use unencrypted network traffic or + encrypted network traffic (TLS). The default value is *tcp*. + + The ``https_proxy`` parameter is expected to be a string which indicates + the name or IP address of a proxy host to use for tunneling secure + connections. + + The ``https_proxy_port`` parameter is expected to be an integer which + indicates the port that is to be used to communicate with the proxy host. + The default value is *0*. + + The ``service_name`` parameter is expected to be a string which indicates + the service name of the database. + + The ``instance_name`` parameter is expected to be a string which indicates + the instance name of the database. + + The ``sid`` parameter is expected to be a string which indicates the SID of + the database. It is recommended to use ``service_name`` instead. + + The ``server_type`` parameter is expected to be a string that indicates the + type of server connection that should be established. If specified, it + should be one of *dedicated*, *shared*, or *pooled*. + + The ``cclass`` parameter is expected to be a string that identifies the + connection class to use for :ref:`drcp`. + + The ``purity`` parameter is expected to be one of the + :ref:`oracledb.PURITY_* ` constants that identifies the + purity to use for DRCP. The purity will internally default to + :data:`~oracledb.PURITY_SELF` for pooled connections. + + The ``expire_time`` parameter is expected to be an integer which indicates + the number of minutes between the sending of keepalive probes. If this + parameter is set to a value greater than zero it enables keepalive. The + default value is *0* minutes. + + The ``retry_count`` parameter is expected to be an integer that identifies + the number of times that a connection attempt should be retried before the + attempt is terminated. The default value is *0*. + + The ``retry_delay`` parameter is expected to be an integer that identifies + the number of seconds to wait before making a new connection attempt. The + default value is *1* seconds. + + The ``tcp_connect_timeout`` parameter is expected to be a float that + indicates the maximum number of seconds to wait for establishing a + connection to the database host. The default value is *20.0* seconds. + + The ``ssl_server_dn_match`` parameter is expected to be a boolean that + indicates whether the server certificate distinguished name (DN) should be + matched in addition to the regular certificate verification that is + performed. Note that if the ``ssl_server_cert_dn`` parameter is not + provided, host name matching is performed instead. The default value is + *True*. + + The ``ssl_server_cert_dn`` parameter is expected to be a string that + indicates the distinguished name (DN) which should be matched with the + server. This value is ignored if the ``ssl_server_dn_match`` parameter is + not set to the value *True*. + + The ``wallet_location`` parameter is expected to be a string that + identifies the directory where the wallet can be found. In python-oracledb + Thin mode, this must be the directory of the PEM-encoded wallet file, + ewallet.pem. + + The ``events`` parameter is ignored in the python-oracledb Thin mode. + + The ``externalauth`` parameter is ignored in the python-oracledb Thin mode. + + If the ``mode`` parameter is specified, it must be one of the + :ref:`connection authorization modes ` + which are defined at the module level. The default value is + :data:`oracledb.AUTH_MODE_DEFAULT`. + + The ``disable_oob`` parameter is expected to be a boolean that indicates + whether out-of-band breaks should be disabled. This value has no effect + on Windows which does not support this functionality. The default value + is *False*. + + The ``stmtcachesize`` parameter is expected to be an integer which + specifies the initial size of the statement cache. The default is the + value of :attr:`defaults.stmtcachesize`. + + The ``tag`` parameter is ignored in the python-oracledb Thin mode. + + The ``matchanytag`` parameter is ignored in the python-oracledb Thin mode. + + The ``config_dir`` parameter is expected to be a string that indicates the + directory in which the :ref:`tnsnames.ora ` configuration file + is located. + + The ``appcontext`` parameter is expected to be a list of 3-tuples that + identifies the application context used by the connection. This parameter + should contain namespace, name, and value and each entry in the tuple + should be a string. + + The ``shardingkey`` parameter and ``supershardingkey`` parameters are + ignored in the python-oracledb Thin mode. + + The ``debug_jdwp`` parameter is expected to be a string with the format + `host=;port=` that specifies the host and port of the PL/SQL + debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug + PL/SQL code invoked by python-oracledb. + + The ``connection_id_prefix`` parameter is expected to be a string and is + added to the beginning of the generated ``connection_id`` that is sent to + the database for `tracing `__. + + The ``ssl_context`` parameter is expected to be an SSLContext object used + for connecting to the database using TLS. This SSL context will be + modified to include the private key or any certificates found in a + separately supplied wallet. This parameter should only be specified if + the default SSLContext object cannot be used. + + The ``sdu`` parameter is expected to be an integer that returns the + requested size of the Session Data Unit (SDU), in bytes. The value tunes + internal buffers used for communication to the database. Bigger values can + increase throughput for large queries or bulk data loads, but at the cost + of higher memory use. The SDU size that will actually be used is negotiated + down to the lower of this value and the database network SDU configuration + value. See the `Database Net Services documentation `__ for more details. The default value is *8192* bytes. + + The ``pool_boundary`` parameter is expected to be one of the strings + *statement* or *transaction* which indicates when pooled :ref:`DRCP ` + or PRCP connections can be returned to the pool. If the value is + *statement*, then pooled DRCP or PRCP connections are implicitly released + back to the DRCP or PRCP pool when the connection is stateless (that is, + there are no active cursors, active transactions, temporary tables, or + temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP + connections are implicitly released back to the DRCP or PRCP pool when + either one of the methods :meth:`AsyncConnection.commit()` or + :meth:`AsyncConnection.rollback()` are called. This parameter requires the + use of DRCP or PRCP with Oracle Database 23ai (or later). See + :ref:`implicitconnpool` for more information. This value is used in both + the python-oracledb Thin and Thick modes. + + The ``use_tcp_fast_open`` parameter is expected to be a boolean which + indicates whether to use TCP Fast Open which is an `Oracle Autonomous + Database Serverless (ADB-S) `__ specific feature that can + reduce the latency in round-trips to the database after a connection has + been established. This feature is only available with certain versions of + ADB-S. This value is used in both python-oracledb Thin and Thick modes. + The default value is *False*. + + The ``ssl_version`` parameter is expected to be one of the constants + *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the + TLS protocol version used. These constants are defined in the Python + `ssl `__ module. This + parameter can be specified when establishing connections with the protocol + *tcps*. This value is used in both python-oracledb Thin and Thick modes. + The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you + are using python-oracledb Thick mode, Oracle Client 23ai is additionally + required. + + The ``use_sni`` parameter is expected to be a boolean which indicates + whether to use the TLS Server Name Indication (SNI) extension to bypass the + second TLS negotiation that would otherwise be required. This parameter is + used in both python-oracledb Thin and Thick modes. This parameter requires + Oracle Database 23.7. The default value is *False*. See the `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 + default is the value of :attr:`defaults.program`. + + The ``machine`` parameter is expected to be a string which specifies the + machine name of the client connecting to Oracle Database. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.machine`. + + The ``terminal`` parameter is expected to be a string which specifies the + terminal identifier from which the connection originates. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.terminal`. + + The ``osuser`` parameter is expected to be a string which specifies the + operating system user that initiates the database connection. This value + is only used in the python-oracledb Thin mode. The default value is the + value of :attr:`defaults.osuser`. + + The ``driver_name`` parameter is expected to be a string which specifies + the driver used by the client to connect to Oracle Database. This value + is used in both the python-oracledb Thin and Thick modes. The default is + the value of :attr:`defaults.driver_name`. + + The ``extra_auth_params`` parameter is expected to be a dictionary + containing the configuration parameters necessary for Oracle Database + authentication using :ref:`OCI ` or :ref:`Azure + ` cloud native authentication plugins. This value is + used in both the python-oracledb Thin and Thick modes. See + :ref:`tokenauth`. + + The ``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``, ``instance_name``, ``use_sni``, + ``thick_mode_dsn_passthrough``, and ``extra_auth_params`` parameters + were added. + + .. versionchanged:: 2.5.0 + + The ``program``, ``machine``, ``terminal``, ``osuser``, and + ``driver_name`` parameters were added. Support for ``edition`` and + ``appcontext`` was added. + + .. versionchanged:: 2.3.0 + + The default value of the ``retry_delay`` parameter was changed from 0 + seconds to 1 second. The default value of the ``tcp_connect_timeout`` + parameter was changed from 60.0 seconds to 20.0 seconds. The + ``ping_timeout`` and ``ssl_version`` parameters were added. + + .. versionchanged:: 2.1.0 + + The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. + + .. versionchanged:: 2.0.0 + + The ``ssl_context`` and ``sdu`` parameters were added. + + .. versionchanged:: 1.4.0 + + The ``connection_id_prefix`` parameter was added. + +.. function:: Cursor(connection) + + Constructor for creating a cursor. Returns a new + :ref:`cursor object ` using the connection. + .. dbapimethodextension:: .. function:: Date(year, month, day) @@ -841,57 +2144,147 @@ Oracledb Methods (number of seconds since the epoch; see the documentation of the standard Python time module for details). + +.. function:: enable_thin_mode() + + Makes python-oracledb be in Thin mode. After this method is called, Thick + mode cannot be enabled. If python-oracledb is already in Thick mode, then + calling ``enable_thin_mode()`` will fail. If Thin mode connections have + already been opened, or a connection pool created in Thin mode, then + calling ``enable_thin_mode()`` is a no-op. + + Since python-oracledb defaults to Thin mode, almost all applications do not + need to call this method. However, because it bypasses python-oracledb's + internal mode-determination heuristic, it may be useful for applications + with multiple threads that concurrently create :ref:`standalone connections + ` when the application starts. + + See :ref:`enablingthin` for more information. + + .. versionadded:: 2.5.0 + +.. function:: get_pool(pool_alias) + + Returns a :ref:`ConnectionPool object ` from the python-oracledb + pool cache. The pool must have been previously created by passing the same + ``pool_alias`` value to :meth:`oracledb.create_pool()` or + :meth:`oracledb.create_pool_async()`. + + If a pool with the given name does not exist, *None* is returned. + + See :ref:`connpoolcache` for more information. + + .. versionadded:: 3.0.0 + .. function:: init_oracle_client(lib_dir=None, config_dir=None, \ error_url=None, driver_name=None) Enables python-oracledb Thick mode by initializing the Oracle Client - library, see :ref:`enablingthick`. 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. - - If the ``lib_dir`` parameter is not None or the empty string, - the specified directory is the only one searched for the Oracle Client - libraries; otherwise, the standard way of locating the Oracle Client - library is used. - - If the ``config_dir`` parameter is not None or the empty string, the - specified directory is used to find Oracle Client library configuration - files. This is equivalent to setting the environment variable ``TNS_ADMIN`` - and overrides any value already set in ``TNS_ADMIN``. If this parameter is - not set, the standard way of locating Oracle Client library configuration - files is used. - - If the ``error_url`` parameter is not None or the empty string, the - specified value is included in the message of the exception raised when the - Oracle Client library cannot be loaded; otherwise, the :ref:`installation` - URL is included. - - If the ``driver_name`` parameter is not None or the empty string, the - specified value can be found in database views that give information about - connections. For example, it is in the ``CLIENT_DRIVER`` column of - ``V$SESSION_CONNECT_INFO``. The standard is to set this value to - ``" : version>"``, where is the name of the driver and - is its version. There should be a single space character before - and after the colon. If this value is not specified, then the default value - in python-oracledb Thick mode is like "python-oracledb thk : ". - - .. note:: - - This method is an extension to the DB API definition. - + The ``lib_dir`` parameter is a string or a bytes object that specifies the + directory containing Oracle Client libraries. If the ``lib_dir`` parameter + is set, then the specified directory is the only one searched for the + Oracle Client libraries; otherwise, the operating system library search + path is used to locate the Oracle Client library. If you are using Python + 3.11 and later, then the value specified in this parameter is encoded + using `locale.getencoding() `__. For all other Python versions, the encoding + "utf-8" is used. If a bytes object is specified in this parameter, then + this value will be used as is without any encoding. + + The ``config_dir`` parameter is a string or a bytes object that specifies + the directory in which the + :ref:`Optional Oracle Net Configuration ` and + :ref:`Optional Oracle Client Configuration ` files reside. + If the ``config_dir`` parameter is set, then the specified directory is + used to find Oracle Client library configuration files. This is + equivalent to setting the environment variable ``TNS_ADMIN`` and overrides + any value already set in ``TNS_ADMIN``. If this parameter is not set, the + :ref:`Oracle standard ` way of locating Oracle Client + library configuration files is used. If you are using Python 3.11 and + later, then the value specified in this parameter is encoded using + `locale.getencoding() `__. For all other Python versions, the encoding + "utf-8" is used. If a bytes object is specified in this parameter, then + this value will be used as is without any encoding. + + The ``error_url`` parameter is a string that specifies the URL which is + included in the python-oracledb exception message if the Oracle Client + libraries cannot be loaded. If the ``error_url`` parameter is set, then + the specified value is included in the message of the exception raised + when the Oracle Client library cannot be loaded; otherwise, the + :ref:`installation` URL is included. This parameter lets your application + display custom installation instructions. + + The ``driver_name`` parameter is a string that specifies the driver name + value. If the ``driver_name`` parameter is set, then the specified value + can be found in database views that give information about connections. + For example, it is in the CLIENT_DRIVER column of the + V$SESSION_CONNECT_INFO view. From Oracle Database 12.2, the name displayed + can be 30 characters. The standard is to set this value to ``" : + version>"``, where is the name of the driver and is its + version. There should be a single space character before and after the + colon. If this parameter is not set, then the value specified in + :attr:`oracledb.defaults.driver_name ` is used. If + the value of this attribute is *None*, then the default value in + python-oracledb Thick mode is like "python-oracledb thk : ". See + :ref:`otherinit`. + + At successful completion of a call to ``oracledb.init_oracle_client()``, + the attribute :attr:`defaults.config_dir` will be set as determined below + (first one wins): + + - the value of the ``oracledb.init_oracle_client()`` parameter + ``config_dir``, if one was passed. + + - the value of :attr:`defaults.config_dir` if it has one. I.e. + :attr:`defaults.config_dir` remains unchanged after + ``oracledb.init_oracle_client()`` completes. + + - the value of the environment variable ``$TNS_ADMIN``, if it is set. + + - the value of ``$ORACLE_HOME/network/admin`` if the environment variable + ``$ORACLE_HOME`` is set. + + - the directory of the loaded Oracle Client library, appended with + ``network/admin``. Note this directory is not determinable on AIX. + + - otherwise the value *None* is used. (Leaving :attr:`defaults.config_dir` + unchanged). + + .. 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 + + The values supplied to the ``lib_dir`` and ``config_dir`` parameters + are encoded using the encoding returned by `locale.getencoding() + `__ + for Python 3.11 and higher; for all other versions, the encoding + "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 @@ -900,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. - - .. note:: + mode. The attribute :attr:`ConnectionPool.thin` can be used to check a + pool's mode. - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. versionadded:: 1.1.0 @@ -914,30 +2306,39 @@ 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 :ref:`ConnectParams class ` instead. - - .. note:: + Use the :meth:`oracledb.ConnectParams()` method instead. - 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, \ - wait_timeout=0, max_lifetime_session=0, session_callback=None, \ - max_sessions_per_shard=0, soda_metadata_cache=False, ping_interval=60, \ - 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=0, tcp_connect_timeout=60.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, handle=0) + getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, timeout=0, \ + wait_timeout=0, max_lifetime_session=0, session_callback=None, \ + max_sessions_per_shard=0, soda_metadata_cache=False, \ + ping_interval=60, ping_timeout=5000, user=None, proxy_user=Nonde, \ + password=None, newpassword=None, wallet_password=None, \ + access_token=None, host=None, port=1521, protocol="tcp", \ + https_proxy=None, https_proxy_port=0, service_name=None, \ + instance_name=None, sid=None, server_type=None, cclass=None, \ + purity=oracledb.PURITY_DEFAULT, expire_time=0, retry_count=0, \ + retry_delay=1, tcp_connect_timeout=20.0, ssl_server_dn_match=True, \ + ssl_server_cert_dn=None, wallet_location=None, events=False, \ + externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, \ + disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, \ + edition=None, tag=None, matchanytag=False, \ + config_dir=oracledb.defaults.config_dir, appcontext=[], \ + shardingkey=[], supershardingkey=[], debug_jdwp=None, \ + connection_id_prefix=None, ssl_context=None, sdu=8192, \ + pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ + program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ + terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=0) Creates and returns a :ref:`PoolParams Object `. The object can be passed to :meth:`oracledb.create_pool()`. @@ -945,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 @@ -967,22 +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. If the - value of this parameter is 0, then the connections are never terminated. - The default value is 0. + connection may remain idle in the pool before it is terminated. This + applies only when the pool has more than ``min`` connections open, allowing + it to shrink to the specified minimum size. The default value is *0* + seconds. A value of *0* means there is no limit. The ``wait_timeout`` parameter is the length of time (in milliseconds) that a caller should wait when acquiring a connection from the pool with ``getmode`` set to :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default - value is 0. + 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 @@ -990,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 @@ -1002,7 +2408,15 @@ 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 + to respond to any internal ping to the database. If the ping does not + respond within the specified time, then the connection is destroyed and + :meth:`~ConnectionPool.acquire()` returns a different connection. This + value is used in both the python-oracledb Thin and Thick modes. The default + value is *5000* milliseconds. The ``user`` parameter is expected to be a string which indicates the name of the user to connect to. This value is used in both the python-oracledb @@ -1033,10 +2447,10 @@ Oracledb Methods for Open Authorization (OAuth 2.0) token based authentication. If it is a 2-tuple, it specifies the token and private key strings used for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based - authentication. If it is a callable, it returns either a string or a 2-tuple - used for OAuth 2.0 or OCI IAM token based authentication and is useful when - the pool needs to expand and create new connections but the current - authentication token has expired. This value is used in both the + authentication. If it is a callable, it returns either a string or a + 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is + useful when the pool needs to expand and create new connections but the + current authentication token has expired. This value is used in both the python-oracledb Thin and Thick modes. The ``host`` parameter is expected to be a string which specifies the name @@ -1045,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 @@ -1060,25 +2475,29 @@ 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 - connection class to use for Database Resident Connection Pooling (DRCP). - This value is used in both the python-oracledb Thin and Thick modes. + connection class to use for :ref:`drcp`. This value is used in both the + python-oracledb Thin and Thick modes. The ``purity`` parameter is expected to be one of the :ref:`oracledb.PURITY_* ` constants that identifies the @@ -1090,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 0. + 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 60.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 @@ -1128,23 +2547,24 @@ Oracledb Methods and Thick modes. The ``externalauth`` parameter is a boolean that determines whether to use - external authentication. This value is only used in the python-oracledb Thick - mode. The default value is False. + external authentication. This value is only used in the python-oracledb + Thick mode. The default value is *False*. The ``events`` parameter is expected to be a boolean that specifies whether the events mode should be enabled. This value is only used in the python-oracledb Thick mode. This parameter is needed for continuous query notification and high availability event notifications. The default - value is False. + value is *False*. The ``mode`` parameter is expected to be an integer that identifies the authorization mode to use. This value is used in both the python-oracledb - Thin and Thick modes.The default value is :data:`oracledb.AUTH_MODE_DEFAULT`. + Thin and Thick modes.The default value is + :data:`oracledb.AUTH_MODE_DEFAULT`. The ``disable_oob`` parameter is expected to be a boolean that indicates whether out-of-band breaks should be disabled. This value is only used in the python-oracledb Thin mode and has no effect on Windows which - does not support this functionality. The default value is False. + 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 @@ -1152,9 +2572,9 @@ Oracledb Methods :attr:`defaults.stmtcachesize`. The ``edition`` parameter is expected to be a string that indicates the - edition to use for the connection. This parameter cannot be used - simultaneously with the ``cclass`` parameter. This value is used in the - python-oracledb Thick mode. + edition to use for the connection. It requires Oracle Database 11.2, or + later. This parameter cannot be used simultaneously with the ``cclass`` + parameter. The ``tag`` parameter is expected to be a string that identifies the type of connection that should be returned from a pool. This value is only used @@ -1163,27 +2583,23 @@ 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 should contain namespace, name, and value and each entry in the tuple - should be a string. This value is only used inthe python-oracledb Thick - mode. + should be a string. - The ``shardingkey`` parameter is expected to be a list of strings, numbers, - bytes or dates that identifies the database shard to connect to. This value - is only used in the python-oracledb Thick mode. - - The ``supershardingkey`` parameter is expected to be a list of strings, - numbers, bytes or dates that identifies the database shard to connect to. - This value is only used in the python-oracledb Thick mode. + The ``shardingkey`` parameter and ``supershardingkey`` parameters, if + specified, are expected to be a sequence of values which identifies the + database shard to connect to. The key values can be a list of strings, + numbers, bytes, or dates. These values are only used in the + python-oracledb Thick mode and are ignored in the Thin mode. See + :ref:`connsharding`. The ``debug_jdwp`` parameter is expected to be a string with the format `host=;port=` that specifies the host and port of the PL/SQL @@ -1193,10 +2609,286 @@ Oracledb Methods ``ORA_DEBUG_JDWP`` environment variable which has the same syntax. For more information, see :ref:`jdwp`. + The ``connection_id_prefix`` parameter is expected to be a string and is + added to the beginning of the generated ``connection_id`` that is sent to + the database for `tracing `__. This value + is only used in the python-oracledb Thin mode. + + The ``ssl_context`` parameter is expected to be an `SSLContext object + `__ which is used + for connecting to the database using TLS. This SSL context will be + modified to include the private key or any certificates found in a + separately supplied wallet. This parameter should only be specified if + the default SSLContext object cannot be used. This value is only used in + the python-oracledb Thin mode. + + The ``sdu`` parameter is expected to be an integer that returns the + requested size of the Session Data Unit (SDU), in bytes. The value tunes + internal buffers used for communication to the database. Bigger values can + increase throughput for large queries or bulk data loads, but at the cost + of higher memory use. The SDU size that will actually be used is negotiated + down to the lower of this value and the database network SDU configuration + value. See the `Database Net Services documentation `__ for more details. This value is used in both the + python-oracledb Thin and Thick modes. The default value is *8192* bytes. + + The ``pool_boundary`` parameter is expected to be one of the strings + *statement* or *transaction* which indicates when pooled :ref:`DRCP ` + or PRCP connections can be returned to the pool. If the value is + *statement*, then pooled DRCP or PRCP connections are implicitly released + back to the DRCP or PRCP pool when the connection is stateless (that is, + there are no active cursors, active transactions, temporary tables, or + temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP + connections are implicitly released back to the DRCP or PRCP pool when + either one of the methods :meth:`Connection.commit()` or + :meth:`Connection.rollback()` are called. This parameter requires the use + of DRCP or PRCP with Oracle Database 23ai (or later). See + :ref:`implicitconnpool` for more information. This value is used in both + the python-oracledb Thin and Thick modes. + + The ``use_tcp_fast_open`` parameter is expected to be a boolean which + indicates whether to use TCP Fast Open which is an `Oracle Autonomous + Database Serverless (ADB-S) `__ specific feature that can + reduce the latency in round-trips to the database after a connection has + been established. This feature is only available with certain versions of + ADB-S. This value is used in both python-oracledb Thin and Thick modes. + The default value is *False*. + + The ``ssl_version`` parameter is expected to be one of the constants + *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the + TLS protocol version used. These constants are defined in the Python + `ssl `__ module. This + parameter can be specified when establishing connections with the protocol + "tcps". This value is used in both python-oracledb Thin and Thick modes. + The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you + are using python-oracledb Thick mode, Oracle Client 23ai is additionally + required. + + The ``use_sni`` parameter is expected to be a boolean which indicates + whether to use the TLS Server Name Indication (SNI) extension to bypass the + second TLS negotiation that would otherwise be required. This parameter is + used in both python-oracledb Thin and Thick modes. This parameter requires + Oracle Database 23.7. The default value is *False*. See the `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 + default is the value of :attr:`defaults.program`. + + The ``machine`` parameter is expected to be a string which specifies the + machine name of the client connecting to Oracle Database. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.machine`. + + The ``terminal`` parameter is expected to be a string which specifies the + terminal identifier from which the connection originates. This value is + only used in the python-oracledb Thin mode. The default is the value of + :attr:`defaults.terminal`. + + The ``osuser`` parameter is expected to be a string which specifies the + operating system user that initiates the database connection. This value + is only used in the python-oracledb Thin mode. The default value is the + value of :attr:`defaults.osuser`. + + The ``driver_name`` parameter is expected to be a string which specifies + the driver used by the client to connect to Oracle Database. This value + is used in both the python-oracledb Thin and Thick modes. The default is + the value of :attr:`defaults.driver_name`. + + The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean + which indicates whether the connect string should be passed unchanged to + the Oracle Client libraries for parsing when using python-oracledb Thick + mode. If this parameter is set to *False* in Thick mode, connect strings + are parsed by python-oracledb itself and a generated connect descriptor is + sent to the Oracle Client libraries. This value is only used in the + python-oracledb Thick mode. The default value is + :attr:`defaults.thick_mode_dsn_passthrough`. For more information, see + :ref:`usingconfigfiles`. + + The ``extra_auth_params`` parameter is expected to be a dictionary + containing the configuration parameters necessary for Oracle Database + authentication using :ref:`OCI ` or :ref:`Azure + ` cloud native authentication plugins. This value is + used in both the python-oracledb Thin and Thick modes. See + :ref:`tokenauth`. + + 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 + + The ``program``, ``machine``, ``terminal``, ``osuser``, and + ``driver_name`` parameters were added. Support for ``edition`` and + ``appcontext`` was added to python-oracledb Thin mode. + + .. versionchanged:: 2.3.0 + + The default value of the ``retry_delay`` parameter was changed from *0* + seconds to *1* second. The default value of the ``tcp_connect_timeout`` + parameter was changed from *60.0* seconds to *20.0* seconds. The + ``ping_timeout`` and ``ssl_version`` parameters were added. + + .. versionchanged:: 2.1.0 + + The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. + + .. versionchanged:: 2.0.0 + + The ``ssl_context`` and ``sdu`` parameters were added. + + .. versionchanged:: 1.4.0 + + The ``connection_id_prefix`` parameter was added. + +.. function:: SparseVector(num_dimensions, indices, values) + + Creates and returns a :ref:`SparseVector object `. + + The ``num_dimensions`` parameter is the number of dimensions contained in + the vector. + + The ``indices`` parameter is the indices (zero-based) of non-zero values + in the vector. + + The ``values`` parameter is the non-zero values stored in the vector. + + .. versionadded:: 3.0.0 + +.. function:: register_params_hook(hook_function) + + Registers a user parameter hook function that will be called internally by + python-oracledb prior to connection or pool creation. The hook function + accepts a copy of the parameters that will be used to create the pool or + standalone connection and may modify them. For example, the cloud native + authentication plugins modify the "access_token" parameter with a function + that will acquire the token using information found in the + "extra_auth_parms" parameter. + + Multiple hooks may be registered. They will be invoked in order of + registration. + + 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 password hook function that will be called internally by + python-oracledb when a password is supplied as a dictionary containing the + given ``password_type`` as the key "type". The hook function is called for + passwords specified as the ``password``, ``newpassword`` and + ``wallet_parameter`` parameters in calls to :meth:`oracledb.connect()`, + :meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, and + :meth:`oracledb.create_pool_async()`. + + Your hook function is expected to accept the dictionary supplied by the + application and return the valid password. + + Calling :meth:`~oracledb.register_password_type()` with the + ``hook_function`` parameter set to *None* will result in a previously + registered user function being removed and the default behavior restored. + + See :ref:`registerpasswordtype`. + + .. dbapimethodextension:: + + .. versionadded:: 3.0.0 + +.. function:: register_protocol(protocol, hook_function) + + Registers a user protocol hook function that will be called internally by + python-oracledb Thin mode prior to connection or pool creation. The hook + function will be invoked when :func:`oracledb.connect`, + :func:`oracledb.create_pool`, :meth:`oracledb.connect_async()`, or + :meth:`oracledb.create_pool_async()` are called with a ``dsn`` parameter + value prefixed with the specified protocol. The user function will also be + invoked when :meth:`ConnectParams.parse_connect_string()` is called in Thin + or Thick modes with a similar ``connect_string`` parameter value. + + Your hook function is expected to construct valid connection details. For + example, if a hook function is registered for the "ldaps" protocol, then + calling :func:`oracledb.connect` with a connection string prefixed with + "ldaps://" will invoke the function. The function can then perform LDAP + lookup to retrieve and set the actual database information that will be + used internally by python-oracledb to complete the connection creation. + + The ``protocol`` parameter is a string that will be matched against the + prefix appearing before "://" in connection strings. + + The ``hook_function`` parameter should be a function with the signature:: + + hook_function(protocol, protocol_arg, params) + + The hook function will be called with the following arguments: + + - The ``protocol`` parameter is the value that was registered. + + - The ``protocol_arg`` parameter is the section after "://" in the + connection string used in the connection or pool creation call, or passed + to :meth:`~ConnectParams.parse_connect_string()`. + + - The ``params`` parameter is an instance of :ref:`ConnectParams + `. + + When your hook function is invoked internally prior to connection or pool + creation, ``params`` will be the ConnectParams instance originally passed + to the :func:`oracledb.connect`, :func:`oracledb.create_pool`, + :meth:`oracledb.connect_async()`, or :meth:`oracledb.create_pool_async()` + call, if such an instance was passed. Otherwise it will be a new + ConnectParams instance. The hook function should parse ``protocol`` and + ``protocol_arg`` and take any desired action to update ``params`` + :ref:`attributes ` with appropriate connection + parameters. Attributes can be set using :meth:`ConnectParams.set()` or + :meth:`ConnectParams.parse_connect_string()`. The ConnectParams instance + will then be used to complete the connection or pool creation. + + When your hook function is invoked by + :meth:`ConnectParams.parse_connect_string()`, then ``params`` will be the + invoking ConnectParams instance that you can update using + :meth:`ConnectParams.set()` or + :meth:`ConnectParams.parse_connect_string()`. + + Internal hook functions for the "tcp" and "tcps" protocols are + pre-registered but can be overridden if needed. If any other protocol has + not been registered, then connecting will result in the error ``DPY-4021: + invalid protocol``. + + Calling :meth:`~oracledb.register_protocol()` with the ``hook_function`` + parameter set to *None* will result in a previously registered user function + being removed and the default behavior restored. + + See :ref:`registerprotocolhook` for more information. + + .. dbapimethodextension:: + + .. versionadded:: 2.5.0 .. function:: Time(hour, minute, second) @@ -1204,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) @@ -1216,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) @@ -1229,6 +2921,52 @@ 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: + +Oracledb IntervalYM Class +========================= + +Objects of this class are returned for columns of type INTERVAL YEAR TO MONTH +and can be passed to variables of type :data:`oracledb.DB_TYPE_INTERVAL_YM` +The class is a `collections.namedtuple() +`__ +class with two integer attributes, ``years`` and ``months``. + +.. versionadded:: 2.2.0 + + +.. _jsonid: + +Oracledb JsonId Class +===================== + +Objects of this class are returned by :ref:`SODA ` in the ``_id`` +attribute of documents stored in native collections when using Oracle Database +23.4 (and later). It is a subclass of the `bytes `__ class. + +.. versionadded:: 2.1.0 + + +.. _futureobj: + +Oracledb __future__ Object +========================== + +Special object that contains attributes which control the behavior of +python-oracledb, allowing for opting in for new features. + +.. dbapimethodextension:: .. _constants: @@ -1243,15 +2981,6 @@ General String constant stating the supported DB API level. Currently '2.0'. -.. data:: buildtime - - String constant stating the time when the binary was built. - - .. note:: - - This constant is an extension to the DB API definition. - - .. data:: paramstyle String constant stating the type of parameter marker formatting expected by @@ -1266,42 +2995,46 @@ General resource without wrapping it using a mutex semaphore to implement resource locking. - Note that in order to make use of multiple threads in a program which - intends to connect and disconnect in different threads, the ``threaded`` - parameter to :meth:`connect()` must be True. - - .. data:: version .. data:: __version__ String constant stating the version of the module. Currently '|release|'. - .. note:: - - This attribute is an extension to the DB API definition. + .. 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 -: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 -: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. - +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()`, :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()`, :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 @@ -1318,11 +3051,13 @@ parameter to the :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` and 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 @@ -1353,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 @@ -1386,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 @@ -1407,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 @@ -1428,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 @@ -1449,12 +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:`Connection.deq()` 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 @@ -1479,31 +3229,33 @@ values for the :attr:`~MessageProperties.state` attribute of the 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 This constant is a possible value for the :attr:`~MessageProperties.delay` attribute of the :ref:`message properties object ` passed as the ``msgproperties`` parameter to the :meth:`Queue.deqone()` or - :meth:`Queue.deqmany()` and :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` - methods. It specifies that no delay should be imposed and the message should - be immediately available for dequeuing. This is also the default value. + :meth:`Queue.deqmany()` and :meth:`Queue.enqone()` or + :meth:`Queue.enqmany()` methods. It specifies that no delay should be + imposed and the message should be immediately available for dequeuing. This + is also the default value. .. data:: MSG_NO_EXPIRATION This constant is a possible value for the :attr:`~MessageProperties.expiration` attribute of the - :ref:`message properties object ` passed as the ``msgproperties`` - parameter to the :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` and - :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` methods. It specifies - that the message never expires. This is also the default value. + :ref:`message properties object ` passed as the + ``msgproperties`` parameter to the :meth:`Queue.deqone()` or + :meth:`Queue.deqmany()` and :meth:`Queue.enqone()` or + :meth:`Queue.enqmany()` methods. It specifies that the message never + expires. This is also the default value. .. _connection-authorization-modes: @@ -1511,137 +3263,223 @@ constants used in advanced queuing. Connection Authorization Modes ------------------------------ -These constants are extensions to the DB API definition and have deprecated the -`authorization modes `_ used in cx_Oracle 8.3. They are -possible values for the ``mode`` parameter of the :meth:`connect()` method. +The Connection Authorization mode constants belong to the enumeration called +``AuthMode``. They are possible values for the ``mode`` parameters of +:meth:`oracledb.connect()`, :meth:`oracledb.create_pool()`, +:meth:`oracledb.connect_async()`, and :meth:`oracledb.create_pool_async()`. +These constants have deprecated the authorization modes used in the obsolete +cx_Oracle driver. +.. dbapiconstantextension:: + +.. versionchanged:: 2.3.0 + + The integer constants for the connection authorization modes were replaced + with the enumeration ``AuthMode``. .. data:: AUTH_MODE_DEFAULT This constant is used to specify that default authentication is to take place. This is the default value if no mode is passed at all. - .. 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. + 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. - .. 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. - .. 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.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. - .. 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. - .. 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. - .. 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.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. - .. 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. - .. 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. - .. note:: + It can be used for standalone and pooled connections in python-oracledb + Thin mode, and for standalone connections in Thick mode. + + Its enumerated value can also be identified by + ``oracledb.AuthMode.SYSRAC``. + + This constant deprecates the ``SYSRAC`` constant that was used in the + obsolete cx_Oracle driver. + +.. _pipeline-operation-types: + +Pipeline Operation Types +------------------------ + +The Pipeline Operation type constants belong to the enumeration called +``PipelineOpType``. The pipelining constants listed below are used to identify +the type of operation added. They are possible values for the +:attr:`PipelineOp.op_type` attribute. + +.. versionadded:: 2.4.0 + +.. data:: oracledb.PIPELINE_OP_TYPE_CALL_FUNC + + This constant identifies the type of operation as the calling of a stored + function. + + This enumerated value can also be identified by + ``oracledb.PipelineOpType.CALL_FUNC``. + +.. data:: oracledb.PIPELINE_OP_TYPE_CALL_PROC + + This constant identifies the type of operation as the calling of a stored + procedure. + + This enumerated value can also be identified by + ``oracledb.PipelineOpType.CALL_PROC``. + +.. data:: oracledb.PIPELINE_OP_TYPE_COMMIT - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. + This constant identifies the type of operation as the performing of a + commit. - This constant deprecates the ``SYSRAC`` constant that was used in - cx_Oracle 8.3. + This enumerated value can also be identified by + ``oracledb.PipelineOpType.COMMIT``. +.. data:: oracledb.PIPELINE_OP_TYPE_EXECUTE + + This constant identifies the type of operation as the executing of a + statement. + + This enumerated value can also be identified by + ``oracledb.PipelineOpType.EXECUTE``. + +.. data:: oracledb.PIPELINE_OP_TYPE_EXECUTE_MANY + + This constant identifies the type of operations as the executing of a + statement multiple times. + + This enumerated value can also be identified by + ``oracledb.PipelineOpType.EXECUTE_MANY``. + +.. data:: oracledb.PIPELINE_OP_TYPE_FETCH_ALL + + This constant identifies the type of operation as the executing of a + query and returning all of the rows from the result set. + + This enumerated value can also be identified by + ``oracledb.PipelineOpType.FETCH_ALL``. + +.. data:: oracledb.PIPELINE_OP_TYPE_FETCH_MANY + + This constant identifies the type of operation as the executing of a + query and returning up to the specified number of rows from the result + set. + + This enumerated value can also be identified by + ``oracledb.PipelineOpType.FETCH_MANY``. + +.. data:: oracledb.PIPELINE_OP_TYPE_FETCH_ONE + + This constant identifies the type of operation as the executing of a query + and returning the first row of the result set. + + This enumerated value can also be identified by + ``oracledb.PipelineOpType.FETCH_ONE``. Database Shutdown Modes ----------------------- -These constants are extensions to the DB API definition. They are possible -values for the ``mode`` parameter of the :meth:`Connection.shutdown()` method. +The Database Shutdown mode constants are possible values for the ``mode`` +parameter of the :meth:`Connection.shutdown()` method. +.. dbapiconstantextension:: .. data:: DBSHUTDOWN_ABORT @@ -1682,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 @@ -1740,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 @@ -1795,68 +3635,99 @@ also used by the :attr:`MessageTable.operation` or Connection Pool Get Modes ------------------------- -These constants are extensions to the DB API definition and have deprecated the -`Session Pool Get Modes `_ constants that were used in cx_Oracle -8.3. They are possible values for the ``getmode`` parameter of the -:meth:`oracledb.create_pool()` method. +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. These constants have +deprecated the Session Pool mode constants that were used in the obsolete +cx_Oracle driver. + +.. dbapiconstantextension:: + +.. versionchanged:: 2.3.0 + The integer constants for the connection pool creation, reconfiguration, + and acquisition ``getmode`` parameters were replaced with the enumeration + ``PoolGetMode``. .. data:: POOL_GETMODE_FORCEGET - This constant is used to specify that a new connection will be returned if - there are no free sessions available in the pool. + This constant is used to specify that a new connection should be created + and returned by :meth:`ConnectionPool.acquire()` if there are no free + connections available in the pool and the pool is already at its maximum + size. - .. note:: + When a connection acquired in this mode is eventually released back to the + pool, it will be dropped and not added to the pool if the pool is still at + its maximum size. + + This enumerated value can also be identified by + ``oracledb.PoolGetMode.FORCEGET``. - This constant deprecates the ``SPOOL_ATTRVAL_FORCEGET`` constant that - was used in cx_Oracle 8.3. + This constant deprecates the ``SPOOL_ATTRVAL_FORCEGET`` constant that was + used in the obsolete cx_Oracle driver. .. data:: POOL_GETMODE_NOWAIT - This constant is used to specify that an exception should be raised if - there are no free sessions available in the pool. + This constant is used to specify that an exception should be raised by + :meth:`ConnectionPool.acquire()` when all currently created connections are + already in use and so :meth:`~ConnectionPool.acquire()` cannot immediately + return a connection. Note the exception may occur even if the pool is + smaller than its maximum size. - .. note:: + This enumerated value can also be identified by + ``oracledb.PoolGetMode.NOWAIT``. - This constant deprecates the ``SPOOL_ATTRVAL_NOWAIT`` constant that was - used in cx_Oracle 8.3. + This constant deprecates the ``SPOOL_ATTRVAL_NOWAIT`` constant that was + used in the obsolete cx_Oracle driver, and was the default ``getmode`` + value. .. data:: POOL_GETMODE_WAIT - This constant is used to specify that the caller should wait until a - session is available if there are no free sessions available in the pool. - This is the default value. + This constant is used to specify that :meth:`ConnectionPool.acquire()` + should wait until a connection is available if there are currently no free + connections available in the pool. This is the default value. - .. note:: + 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 - This constant is used to specify that the caller should wait for a period - of time (defined by the ``wait_timeout`` parameter) for a session to become - available before returning with an error. + This constant is used to specify that :meth:`ConnectionPool.acquire()` + should wait for a period of time (defined by the ``wait_timeout`` + parameter) for a connection to become available before returning with an + error. - .. note:: + This enumerated value can also be identified by + ``oracledb.PoolGetMode.TIMEDWAIT``. - This constant deprecates the ``SPOOL_ATTRVAL_TIMEDWAIT`` constant that - was used in cx_Oracle 8.3. + This constant deprecates the ``SPOOL_ATTRVAL_TIMEDWAIT`` constant that was + used in the obsolete cx_Oracle driver. .. _drcppurityconsts: Connection Pool Purity Constants -------------------------------- -These constants are extensions to the DB API definition and have deprecated the -`Session Pool Purity `_ constants that were used in cx_Oracle 8.3. -They are possible values for the ``purity`` parameter of the :meth:`connect()` -method, which is used in Database Resident Connection Pooling (DRCP). +The Connection Pool Purity constants belong to the enumeration called +``Purity``. They are possible values for the :ref:`drcp` ``purity`` parameter +of :meth:`oracledb.create_pool()`, :meth:`ConnectionPool.acquire()`, +:meth:`oracledb.connect()`, :meth:`oracledb.create_pool_async()`, and +:meth:`oracledb.connect_async()`. These constants have deprecated the Session +Pool purity constants that were used in the obsolete cx_Oracle driver. + +.. dbapiconstantextension:: + +.. versionchanged:: 2.3.0 + + The integer constants for the connection pool get modes were replaced + with the enumeration ``Purity``. .. data:: PURITY_DEFAULT @@ -1864,20 +3735,21 @@ method, which is used in Database Resident Connection Pooling (DRCP). default value identified by Oracle (see Oracle's documentation for more information). This is the default value. - .. note:: + This enumerated value can also be identified by + ``oracledb.Purity.DEFAULT``. - This constant deprecates the ``ATTR_PURITY_DEFAULT`` constant that was - used in cx_Oracle 8.3. + This constant deprecates the ``ATTR_PURITY_DEFAULT`` constant that was used + in the obsolete cx_Oracle driver, and was the default ``purity`` value. .. data:: PURITY_NEW This constant is used to specify that the session acquired from the pool should be new and not have any prior session state. - .. note:: + 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. + This constant deprecates the ``ATTR_PURITY_NEW`` constant that was used in + the obsolete cx_Oracle driver. .. data:: PURITY_SELF @@ -1885,17 +3757,18 @@ method, which is used in Database Resident Connection Pooling (DRCP). This constant is used to specify that the session acquired from the pool need not be new and may have prior session state. - .. note:: + 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. + This constant deprecates the ``ATTR_PURITY_SELF`` constant that was used in + 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 @@ -1906,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 @@ -1928,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 @@ -1948,8 +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 @@ -1995,9 +3872,11 @@ values for the ``protocol`` parameter of the :meth:`Connection.subscribe()` meth 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 @@ -2089,15 +3968,13 @@ All of these types are extensions to the DB API definition. They are found in query and object metadata. They can also be used to specify the database type when binding data. +Also see the table :ref:`supporteddbtypes`. + .. data:: DB_TYPE_BFILE Describes columns, attributes or array elements in a database that are of type BFILE. It will compare equal to the DB API type :data:`BINARY`. - .. note:: - - DB_TYPE_BFILE database type is only supported in the python-oracledb - Thick mode. See :ref:`enablingthick`. .. data:: DB_TYPE_BINARY_DOUBLE @@ -2168,8 +4045,7 @@ when binding data. .. data:: DB_TYPE_INTERVAL_YM Describes columns, attributes or array elements in a database that are of - type INTERVAL YEAR TO MONTH. This database type is not currently supported - by python-oracledb. + type INTERVAL YEAR TO MONTH. .. data:: DB_TYPE_JSON @@ -2177,16 +4053,6 @@ when binding data. Describes columns in a database that are of type JSON (with Oracle Database 21 or later). - .. note:: - - DB_TYPE_JSON database type is only supported in the python-oracledb - Thick mode. See :ref:`enablingthick`. - - In python-oracledb Thin mode, the JSON database type can be fetched - with an output type handler as described in :ref:`Fetching JSON - `. - - .. data:: DB_TYPE_LONG Describes columns, attributes or array elements in a database that are of @@ -2243,10 +4109,6 @@ when binding data. Describes columns, attributes or array elements in a database that are an instance of a named SQL or PL/SQL type. - .. note:: - - This type is not supported in python-oracledb Thin mode. - .. data:: DB_TYPE_RAW @@ -2281,6 +4143,12 @@ when binding data. :data:`DATETIME`. +.. data:: DB_TYPE_UNKNOWN + + Describes columns, attributes or array elements in a database that are + of an unknown type. + + .. data:: DB_TYPE_UROWID Describes columns, attributes or array elements in a database that are of @@ -2298,6 +4166,22 @@ when binding data. type VARCHAR2. It will compare equal to the DB API type :data:`STRING`. +.. data:: DB_TYPE_VECTOR + + Describes columns, attributes or array elements in a database that are of + type VECTOR. + + .. versionadded:: 2.2.0 + + +.. data:: DB_TYPE_XMLTYPE + + Describes columns, attributes or array elements in a database that are of + type SYS.XMLTYPE. + + .. versionadded:: 2.0.0 + + .. _dbtypesynonyms: Database Type Synonyms @@ -2391,7 +4275,7 @@ version of python-oracledb. .. data:: NCHAR - A synonym for :data:`DB_TYPE_NVARCHAR`. + A synonym for :data:`DB_TYPE_NCHAR`. .. deprecated:: cx_Oracle 8.0 @@ -2474,6 +4358,55 @@ below. Suspends the TPC transaction. +.. _vectorformatconstants: + +Vector Format Constants +----------------------- + +These constants belong to the enumeration called ``VectorFormat`` and are +possible values for the :attr:`FetchInfo.vector_format` attribute. + +.. versionadded:: 2.2.0 + +.. versionchanged:: 2.3.0 + + The integer constants for the vector format constants were replaced with + the enumeration ``VectorFormat``. + +.. data:: VECTOR_FORMAT_BINARY + + This constant is used to represent the storage format of VECTOR columns + using 8-bit unsigned integers. + + This enumerated value can also be identified by + ``oracledb.VectorFormat.BINARY``. + + .. versionadded:: 2.3.0 + +.. data:: VECTOR_FORMAT_FLOAT32 + + This constant is used to represent the storage format of VECTOR columns + using 32-bit floating point numbers. + + This enumerated value can also be identified by + ``oracledb.VectorFormat.FLOAT32``. + +.. data:: VECTOR_FORMAT_FLOAT64 + + This constant is used to represent the storage format of VECTOR columns + using 64-bit floating point numbers. + + This enumerated value can also be identified by + ``oracledb.VectorFormat.FLOAT64``. + +.. data:: VECTOR_FORMAT_INT8 + + This constant is used to represent the storage format of VECTOR columns + using 8-bit signed integers. + + This enumerated value can also be identified by + ``oracledb.VectorFormat.INT8``. + .. _exceptions: Oracledb Exceptions @@ -2558,7 +4491,7 @@ See :ref:`exception` for usage information. .. _exchandling: -Oracledb._Error Objects +Oracledb _Error Objects ======================= See :ref:`exception` for usage information. @@ -2601,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 new file mode 100644 index 00000000..326fe95b --- /dev/null +++ b/doc/src/api_manual/pipeline.rst @@ -0,0 +1,263 @@ +.. _pipelineobj: + +********************* +API: Pipeline Objects +********************* + +Pipelining is only supported in python-oracledb Thin mode with +:ref:`asyncio `. See :ref:`pipelining` for more +information about pipelining. + +.. note:: + + True pipelining is only available when connected to Oracle Database 23ai. + +.. versionadded:: 2.4.0 + +.. _pipelineobjs: + +Pipeline Objects +================ + +Pipeline objects represent a pipeline used to execute multiple database +operations. A Pipeline object is created by calling +:meth:`oracledb.create_pipeline()`. + +.. _pipelinemethods: + +Pipeline Methods +---------------- + +.. method:: Pipeline.add_callfunc(name, return_type, parameters=None, keyword_parameters=None) + + Adds an operation to the pipeline that calls a stored PL/SQL function with + the given parameters and return type. The created + :ref:`PipelineOp object ` is also returned from this + function. :ref:`pipelineopattrs` can be used to examine the operation, if + needed. + + When the Pipeline is executed, the + :ref:`PipelineOpResult object ` that is returned for + this operation will have the :attr:`~PipelineOpResult.return_value` + attribute populated with the return value of the PL/SQL function if the + call completes successfully. + +.. method:: Pipeline.add_callproc(name, parameters=None, keyword_parameters=None) + + Adds an operation that calls a stored procedure with the given parameters. + The created :ref:`PipelineOp object ` is also returned + from this function. :ref:`pipelineopattrs` can be used to examine the + operation, if needed. + +.. method:: Pipeline.add_commit() + + Adds an operation that performs a commit. + +.. method:: Pipeline.add_execute(statement, parameters=None) + + Adds an operation that executes a statement with the given parameters. + The created :ref:`PipelineOp object ` is also returned + from this function. :ref:`pipelineopattrs` can be used to examine the + operation, if needed. + + Do not use this for queries that return rows. Instead use + :meth:`Pipeline.add_fetchall()`, :meth:`Pipeline.add_fetchmany()`, or + :meth:`Pipeline.add_fetchone()`. + +.. method:: Pipeline.add_executemany(statement, parameters) + + Adds an operation that executes a SQL statement once using all bind value + mappings or sequences found in the sequence parameters. This can be used to + insert, update, or delete multiple rows in a table. It can also invoke a + PL/SQL procedure multiple times. See :ref:`batchstmnt`. + + The created :ref:`PipelineOp object ` is also returned from + this function. :ref:`pipelineopattrs` can be used to examine the operation, + if needed. + + The ``parameters`` parameter can be a list of tuples, where each tuple item + maps to one bind variable placeholder in ``statement``. It can also be a + list of dictionaries, where the keys match the bind variable placeholder + names in ``statement``. If there are no bind values, or values have + previously been bound, the ``parameters`` value can be an integer + specifying the number of iterations. + +.. method:: Pipeline.add_fetchall(statement, parameters=None, arraysize=None, rowfactory=None) + + Adds an operation that executes a query and returns all of the rows from + the result set. The created :ref:`PipelineOp object ` is + also returned from this function. :ref:`pipelineopattrs` can be used to + examine the operation, if needed. + + When the Pipeline is executed, the :ref:`PipelineOpResult + object ` that is returned for this operation will + have the :attr:`~PipelineOpResult.rows` attribute populated with the list + of rows returned by the query. + + The default value for ``arraysize`` is :attr:`defaults.arraysize`. + + Internally, this operation's :attr:`Cursor.prefetchrows` size is set to the + value of the explicit or default ``arraysize`` parameter value. + +.. method:: Pipeline.add_fetchmany(statement, parameters=None, num_rows=None, rowfactory=None) + + Adds an operation that executes a query and returns up to the specified + number of rows from the result set. The created + :ref:`PipelineOp object ` is also returned from this + function. :ref:`pipelineopattrs` can be used to examine the operation, if + needed. + + When the Pipeline is executed, the + :ref:`PipelineOpResult object ` that is returned for + this operation will have the :attr:`~PipelineOpResult.rows` attribute + populated with the list of rows returned by the query. + + The default value for ``num_rows`` is the value of + :attr:`defaults.arraysize`. + + Internally, this operation's :attr:`Cursor.prefetchrows` size is set to the + value of the explicit or default ``num_rows`` parameter, allowing all rows + to be fetched in one :ref:`round-trip ` + + Since only one fetch is performed for a query operation, consider adding a + ``FETCH NEXT`` clause to the statement to prevent the database processing + rows that will never be fetched, see :ref:`rowlimit`. + +.. method:: Pipeline.add_fetchone(statement, parameters=None, rowfactory=None) + + Adds an operation that executes a query and returns the first row of the + result set if one exists. The created + :ref:`PipelineOp object ` is also returned from this + function. :ref:`pipelineopattrs` can be used to examine the operation, if + needed. + + When the Pipeline is executed, the + :ref:`PipelineOpResult object ` that is returned for + this operation will have the :attr:`~PipelineOpResult.rows` attribute + populated with this row if the query is performed successfully. + + Internally, this operation's :attr:`Cursor.prefetchrows` and + :attr:`Cursor.arraysize` sizes will be set to 1. + + Since only one fetch is performed for a query operation, consider adding a + ``WHERE`` condition or using a ``FETCH NEXT`` clause in the statement to + prevent the database processing rows that will never be fetched, see + :ref:`rowlimit`. + +Pipeline Attributes +------------------- + +.. attribute:: Pipeline.operations + + This read-only attribute returns the list of operations associated with + the pipeline. + +.. _pipelineopobjs: + +PipelineOp Objects +================== + +PipelineOp objects are created by calling the methods in the +:ref:`Pipeline class `. + +.. _pipelineopattrs: + +PipelineOp Attributes +--------------------- + +.. attribute:: PipelineOp.arraysize + + This read-only attribute returns the :ref:`array size ` that + will be used when fetching query rows with :meth:`Pipeline.add_fetchall()`. + For all other operations, the value returned is *0*. + +.. attribute:: PipelineOp.keyword_parameters + + This read-only attribute returns the keyword parameters to the stored + procedure or function being called by the operation, if applicable. + +.. attribute:: PipelineOp.name + + This read-only attribute returns the name of the stored procedure or + function being called by the operation, if applicable. + +.. attribute:: PipelineOp.num_rows + + 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*. + +.. attribute:: PipelineOp.op_type + + This read-only attribute returns the type of operation that is taking + place. See :ref:`pipeline-operation-types` for types of operations. + +.. attribute:: PipelineOp.parameters + + This read-only attribute returns the parameters to the stored procedure or + function or the parameters bound to the statement being executed by the + operation, if applicable. + +.. attribute:: PipelineOp.return_type + + This read-only attribute returns the return type of the stored function + being called by the operation, if applicable. + +.. attribute:: PipelineOp.rowfactory + + This read-only attribute returns the row factory callable function to be + used in a query executed by the operation, if applicable. + +.. attribute:: PipelineOp.statement + + This read-only attribute returns the statement being executed by the + operation, if applicable. + +.. _pipelineopresultobjs: + +PipelineOpResult Objects +======================== + +When :meth:`AsyncConnection.run_pipeline()` is called, it returns a list of +PipelineOpResult objects. These objects contain the results of the executed +:ref:`PipelineOp objects ` operations. + +PipelineOpResult Attributes +--------------------------- + +.. attribute:: PipelineOpResult.columns + + This read-only attribute is a list of :ref:`FetchInfo` + objects. This attribute will be *None* for operations that do not return + rows. + + .. versionadded:: 2.5.0 + +.. attribute:: PipelineOpResult.error + + This read-only attribute returns the error that occurred when running this + operation. If no error occurred, then the value *None* is returned. + +.. attribute:: PipelineOpResult.operation + + This read-only attribute returns the :ref:`PipelineOp ` + operation object that generated the result. + +.. attribute:: PipelineOpResult.return_value + + This read-only attribute returns the return value of the called PL/SQL + function, if a function was called for the operation. + +.. attribute:: PipelineOpResult.rows + + This read-only attribute returns the rows that were fetched by the + operation, if a query was executed. + +.. 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 + `. + + .. versionadded:: 2.5.0 diff --git a/doc/src/api_manual/pool_params.rst b/doc/src/api_manual/pool_params.rst index e1250a12..76d3168d 100644 --- a/doc/src/api_manual/pool_params.rst +++ b/doc/src/api_manual/pool_params.rst @@ -18,34 +18,67 @@ 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, wait_timeout=None, \ - max_lifetime_session=None, session_callback=None, max_sessions_per_shard=None, \ - soda_metadata_cache=None, ping_interval=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, handle=None) +.. method:: PoolParams.set(min=None, max=None, increment=None, \ + connectiontype=None, getmode=None, homogeneous=None, timeout=None, \ + wait_timeout=None, max_lifetime_session=None, session_callback=None, \ + max_sessions_per_shard=None, soda_metadata_cache=None, \ + ping_interval=None, ping_timeout=None, user=None, proxy_user=None, \ + password=None, newpassword=None, wallet_password=None, \ + access_token=None, host=None, port=None, protocol=None, \ + https_proxy=None, https_proxy_port=None, service_name=None, \ + instance_name=None, sid=None, server_type=None, cclass=None, \ + purity=None, expire_time=None, retry_count=None, retry_delay=None, \ + tcp_connect_timeout=None, ssl_server_dn_match=None, \ + ssl_server_cert_dn=None, wallet_location=None, events=None, \ + externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, \ + edition=None, tag=None, matchanytag=None, config_dir=None, \ + appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ + connection_id_prefix=None, ssl_context=None, sdu=None, \ + pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ + program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ + terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ + driver_name=oracledb.defaults.driver_name, use_sni=None, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=None) - Sets one or more of the parameters. + Sets one or more of the parameters. + + .. 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 + ``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: @@ -54,112 +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 the 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 the 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 the 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 the 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 the 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 the 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 the 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 the 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 attribute is supported in both python-oracledb Thin and Thick modes. - This attribute is supported in the 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 the 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 the 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 the 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 the 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 45ee6e5d..8a7cb4cb 100644 --- a/doc/src/api_manual/soda.rst +++ b/doc/src/api_manual/soda.rst @@ -10,6 +10,11 @@ allows documents to be inserted, queried, and retrieved from Oracle Database using a set of NoSQL-style python-oracledb methods. By default, documents are JSON strings. See the :ref:`user manual ` for examples. +.. note:: + + SODA is only supported in the python-oracledb Thick mode. See + :ref:`enablingthick`. + .. _sodarequirements: SODA Requirements @@ -30,52 +35,55 @@ SODA requires Oracle Client 18.3 or higher and Oracle Database 18.1 and higher. .. note:: - If you are using Oracle Database 21c (or later) and create new collections - you need to do one of the following: - - - Use Oracle Client libraries 21c (or later) - - - Or explicitly use collection metadata when creating collections and set - the data storage type to BLOB, for example:: - - { - "keyColumn": { - "name":"ID" - }, - "contentColumn": { - "name": "JSON_DOCUMENT", - "sqlType": "BLOB" - }, - "versionColumn": { - "name": "VERSION", - "method": "UUID" - }, - "lastModifiedColumn": { - "name": "LAST_MODIFIED" - }, - "creationTimeColumn": { - "name": "CREATED_ON" - } + SODA APIs are only supported in the python-oracledb Thick mode. See + :ref:`enablingthick`. + + +If you are using Oracle Database 21c (or later) and create new collections +you need to do one of the following: + +- Use Oracle Client libraries 21c (or later) + +- Or explicitly use collection metadata when creating collections and set + the data storage type to BLOB, for example:: + + { + "keyColumn": { + "name":"ID" + }, + "contentColumn": { + "name": "JSON_DOCUMENT", + "sqlType": "BLOB" + }, + "versionColumn": { + "name": "VERSION", + "method": "UUID" + }, + "lastModifiedColumn": { + "name": "LAST_MODIFIED" + }, + "creationTimeColumn": { + "name": "CREATED_ON" } + } - - Or, set the database initialization parameter `compatible - `__ to 19 or lower. +- Or set the database initialization parameter `compatible + `__ to 19.0.0 or lower - Otherwise, you may get errors such as ``ORA-40842: unsupported value JSON in - the metadata for the field sqlType`` or ``ORA-40659: Data type does not match - the specification in the collection metadata``. +Otherwise, you may get errors such as ``ORA-40842: unsupported value JSON in +the metadata for the field sqlType`` or ``ORA-40659: Data type does not match +the specification in the collection metadata``. .. _sodadb: SodaDatabase Objects ==================== -.. note:: - - The SODA Database object is an extension 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 -------------------- @@ -99,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") @@ -110,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 @@ -145,19 +155,18 @@ 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 ====================== -.. note:: +SODA Collection objects are used to represent SODA collections and is created +by methods :meth:`SodaDatabase.createCollection()` and +:meth:`SodaDatabase.openCollection()`. - The SODA Collection object is an extension the DB API. It is used to - represent SODA collections and is created by methods - :meth:`SodaDatabase.createCollection()` and - :meth:`SodaDatabase.openCollection()`. +.. dbapiobjectextension:: SodaCollection Methods ---------------------- @@ -178,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. @@ -189,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. @@ -215,8 +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) @@ -240,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 `__ @@ -254,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) @@ -273,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 `__ @@ -285,8 +294,17 @@ 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() + + Returns a list of specifications for the indexes found on the collection. + + This method requires Oracle Client 21.3 or later (or Oracle Client 19 from + 19.13). + .. versionadded:: 1.4.0 .. method:: SodaCollection.save(doc) @@ -309,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 `__ @@ -324,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() @@ -339,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 @@ -354,12 +372,12 @@ SodaCollection Attributes SodaDoc Objects =============== -.. note:: +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 `. - The SODA Document object is an extension the DB API. It is returned by the - methods :meth:`SodaDatabase.createDocument()`, - :meth:`SodaOperation.getDocuments()` and :meth:`SodaOperation.getOne()` as - well as by iterating over :ref:`SODA document cursors `. +.. dbapiobjectextension:: SodaDoc Methods --------------- @@ -368,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 @@ -393,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 @@ -408,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 @@ -425,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: @@ -433,12 +451,11 @@ SodaDoc Attributes SodaDocCursor Objects ===================== -.. note:: +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 `. - The SODA Document Cursor object is an extension the DB API. It is returned - by the method :meth:`SodaOperation.getCursor()` and implements the iterator - protocol. Each iteration will return a :ref:`SODA document object - `. +.. dbapiobjectextension:: SodaDocCursor Methods --------------------- @@ -455,11 +472,11 @@ SodaDocCursor Methods SodaOperation Objects ===================== -.. note:: +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()`. - The SODA Operation Object is an extension to the DB API. It represents an - operation that will be performed on all or some of the documents in a SODA - collection. It is created by the method :meth:`SodaCollection.find()`. +.. dbapiobjectextension:: SodaOperation Methods --------------------- @@ -477,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. @@ -523,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. @@ -537,7 +555,6 @@ SodaOperation Methods Use of this method requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11). - .. method:: SodaOperation.key(value) Specifies that the document with the specified key should be returned. @@ -570,6 +587,29 @@ SodaOperation Methods criteria can be specified by chaining methods together. +.. method:: SodaOperation.lock() + + Specifies whether the documents fetched from the collection should be + locked (equivalent to SQL "select for update"). + + The next commit or rollback on the connection made after the operation is + performed will "unlock" the documents. Ensure that the connection is not in + autocommit mode or the documents will be unlocked immediately after the + operation is complete. + + This method should only be used with read operations (other than + :func:`~SodaOperation.count()`) and should not be used in + conjunction with non-terminal methods :meth:`~SodaOperation.skip()` and + :meth:`~SodaOperation.limit()`. + + If this method is specified in conjunction with a write operation this + method is ignored. + + This method is only supported in Oracle Client 21.3 or later (or + Oracle Client 19 from 19.11). + + .. versionadded:: 1.4.0 + .. method:: SodaOperation.remove() Removes all of the documents in the collection that match the criteria. The @@ -600,7 +640,7 @@ SodaOperation Methods Specifies the number of documents that match the other criteria that will be skipped. This method is only usable for read operations such as - :meth:`~SodaOperation.getCursor()` and + :meth:`~SodaOperation.getOne()`, :meth:`~SodaOperation.getCursor()`, and :meth:`~SodaOperation.getDocuments()`. For write operations, any value set using this method is ignored. 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 ae518976..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. @@ -136,8 +132,9 @@ Message Objects This read-only attribute returns a list of message query objects that give information about query result sets changed for this notification. This - attribute will be None if the ``qos`` parameter did not include the flag - :data:`~oracledb.SUBSCR_QOS_QUERY` when the subscription was created. + attribute will be an empty list if the ``qos`` parameter did not include + the flag :data:`~oracledb.SUBSCR_QOS_QUERY` when the subscription was + created. .. attribute:: Message.queue_name @@ -147,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. @@ -170,7 +167,7 @@ Message Objects This read-only attribute returns a list of message table objects that give information about the tables changed for this notification. This - attribute will be None if the ``qos`` parameter included the flag + attribute will be an empty list if the ``qos`` parameter included the flag :data:`~oracledb.SUBSCR_QOS_QUERY` when the subscription was created. @@ -189,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 @@ -218,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 @@ -239,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 4388d76e..0a14e611 100644 --- a/doc/src/api_manual/variable.rst +++ b/doc/src/api_manual/variable.rst @@ -4,9 +4,10 @@ API: Variable Objects ********************* -.. note:: +Variable objects are created with :meth:`Cursor.var()` or +:func:`Cursor.arrayvar()`. - The DB API definition does not define this object. +.. dbapiobjectextension:: Variable Methods ================= @@ -36,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. @@ -46,16 +47,23 @@ 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. +.. attribute:: Variable.convert_nulls + + This read-only attribute returns whether the :attr:`~Variable.outconverter` + method is called when null values are fetched from the database. + + .. versionadded:: 1.4.0 + .. attribute:: Variable.inconverter - This read-write attribute specifies the method used to convert data from + 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 @@ -65,16 +73,16 @@ 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 - This read-write attribute specifies the method used to convert data from + 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 07dd818a..534ccf3a 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -2,10 +2,11 @@ # # python-oracledb documentation build configuration file # -# This file is execfile()d with the current directory set to its containing dir. +# This file is execfile()d with the current directory set to its containing dir # # The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed automatically). +# that aren't pickleable (module imports are okay, they're removed +# automatically). # # All configuration values have a default value; values that are commented out # serve to show the default value. @@ -19,23 +20,33 @@ # General configuration # --------------------- -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ["table_with_summary", "oracle_deprecated"] +# 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", + "dbapi_extension", + "sphinx_rtd_theme", +] # Add any paths that contain templates here, relative to this directory. -templates_path = ['.templates'] +templates_path = [".templates"] # The suffix of source filenames. -source_suffix = '.rst' +source_suffix = ".rst" # The root toctree document. -root_doc = master_doc = 'index' +root_doc = master_doc = "index" # General substitutions. -project = 'python-oracledb' -copyright = u'2016, 2022, 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' -author = 'Oracle' +project = "python-oracledb" +copyright = ( + "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" +) +author = "Oracle" # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. @@ -56,26 +67,26 @@ # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# today = '' # Else, today_fmt is used as the format for a strftime call. -today_fmt = '%B %d, %Y' +today_fmt = "%B %d, %Y" # List of documents that shouldn't be included in the build. -#unused_docs = [] +# unused_docs = [] # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +# show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" # Options for HTML output @@ -87,64 +98,67 @@ # html_style = 'default.css' # The theme to use for readthedocs. -html_theme = 'sphinx_rtd_theme' +html_theme = "sphinx_rtd_theme" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['.static'] +html_static_path = [".static"] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -html_last_updated_fmt = '%b %d, %Y' +html_last_updated_fmt = "%b %d, %Y" # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +# html_use_smartypants = True # Content template for the index page. -#html_index = '' +# html_index = '' # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +# html_additional_pages = {} # If false, no module index is generated. -#html_use_modindex = True +# html_use_modindex = True # If true, the reST sources are included in the HTML build as _sources/. html_copy_source = False # Output file base name for HTML help builder. -htmlhelp_basename = 'oracledbdoc' +htmlhelp_basename = "oracledbdoc" numfig = True + # Display tables with no horizontal scrollbar def setup(app): - app.add_css_file('custom.css') + app.add_css_file("custom.css") + # Options for LaTeX output # ------------------------ # The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' +# latex_paper_size = 'letter' # The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' +# latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, document class [howto/manual]). -#latex_documents = [] +# (source start file, target name, title, author, document class +# [howto/manual]). +# latex_documents = [] # Additional stuff for the LaTeX preamble. -#latex_preamble = '' +# latex_preamble = '' # Documents to append as an appendix to all manuals. -#latex_appendices = [] +# latex_appendices = [] # If false, no module index is generated. -#latex_use_modindex = True +# latex_use_modindex = True diff --git a/doc/src/index.rst b/doc/src/index.rst index 5d20fb7f..43ed1d5a 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -1,19 +1,10 @@ -Welcome to python-oracledb's documentation! -=========================================== +Welcome to python-oracledb's documentation +========================================== -Python-oracledb is the new name for the Python `cx_Oracle driver -`__. The python-oracledb driver is -an open source module that enables Python programs to access Oracle -Database. It conforms to the `Python Database API v2.0 Specification -`__ with a considerable number of -additions and a couple of exclusions. - -This module is currently tested with Python 3.6, 3.7, 3.8, 3.9, and 3.10 -against Oracle Database 21c, 19c, 18c, 12c, and 11.2. - -**python-oracledb** is distributed under an open-source -:ref:`license `. Changes in python-oracledb releases can be found in -the :ref:`release notes `. +The python-oracledb driver is an open source Python module that enables access +to Oracle Database. Python-oracledb is the renamed, major version successor to +cx_Oracle 8.3. The cx_Oracle driver is obsolete and should not be used for new +development. You can use assistive technology products, such as screen readers, while you work with the python-oracledb documentation. You can also use the keyboard @@ -39,18 +30,24 @@ User Guide user_guide/lob_data.rst 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/tracing.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 ========== @@ -62,16 +59,25 @@ API Manual api_manual/module.rst api_manual/defaults.rst api_manual/connection.rst - api_manual/connect_param.rst + api_manual/connect_params.rst 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 .. toctree:: diff --git a/doc/src/license.rst b/doc/src/license.rst index 00e9d1bc..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, 2022 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 608686b0..ee1d5199 100644 --- a/doc/src/release_notes.rst +++ b/doc/src/release_notes.rst @@ -7,18 +7,1477 @@ python-oracledb Release Notes For deprecations, see :ref:`Deprecations `. -oracledb 1.2.0b1 (TBD) ----------------------- +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.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 :ref:`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``. +#) Fixed a memory leak when enqueuing to JSON queues with + :ref:`Oracle Advanced Queuing `. + +Common Changes +++++++++++++++ + +#) Added Instance Principal authentication support when using + :ref:`OCI Cloud Native Authentication `. +#) Improvements to :ref:`data frames `: + + - Fixed date handling to match PyArrow's and avoid localization issues + (`issue 499 `__). + - Fixed bug on Windows when fetching dates prior to 1970 and after 2038 + (`issue 483 `__). + - Added support for the NCHAR, NVARCHAR and NCLOB data types + (`issue 505 `__). + +#) Added parameter ``pool_name`` to connection and pool creation methods to + support Oracle Database 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 `__). +#) Host names are now resolved to IP addresses in python-oracledb instead of + the Python libraries. Address list load balancing and failover settings + will be used when establishing connections. +#) 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. +#) Error ``DPY-6006: The name on the server certificate does not match the + expected value: "{expected_name}"`` is now raised when neither the common + name (CN) nor any of the subject alternative names (SANs) found on the + server certificate match the host name used to connect to the database. +#) The text of error ``DPY-4022: invalid value for DRCP purity {purity}`` + changed to ``DPY-4022: invalid value for enumeration {name}: {value}``. +#) 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. + +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 :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) +------------------------------ + +Thin Mode Changes ++++++++++++++++++ + +#) Fixed bug when table recreation changes the data type of a column from + :data:`oracledb.DB_TYPE_LONG` or :data:`oracledb.DB_TYPE_LONG_RAW` to a + different compatible type + (`issue 424 `__). +#) If the database states that an out-of-band break check should not take + place during connect (by setting the `DISABLE_OOB_AUTO + `__ parameter to TRUE), + python-oracledb no longer attempts to do so + (`issue 419 `__). +#) All exceptions subclassed from ``OSError`` now cause connection retry + attempts, subject to the connection ``retry_count`` and ``retry_delay`` + parameters + (`issue 420 `__). + +Thick Mode Changes +++++++++++++++++++ + +#) Fixed bug calculating property :data:`Connection.max_identifier_length` + when using Oracle Client libraries 12.1, or older. The returned value may + now be ``None`` when the size cannot be reliably determined by + python-oracledb, which occurs when using Oracle Client libraries 12.1 (or + older) to connect to Oracle Database 12.2, or later. + (`ODPI-C `__ dependency update). +#) Fixed bug resulting in a segfault when using external authentication + (`issue 425 `__). + +Common Changes +++++++++++++++ + +#) Fixed bug when fetching empty data from CLOB or BLOB columns marked with + the ``IS JSON`` constraint + (`issue 429 `__). + + +oracledb 2.5.0 (November 2024) +------------------------------ Thin Mode Changes +++++++++++++++++ +#) Added attributes :attr:`Connection.session_id` and + :attr:`Connection.serial_num` that provide information about the session + identifier and session serial number associated with a connection. +#) Added attributes + :attr:`oracledb.defaults.driver_name `, + :attr:`oracledb.defaults.machine `, + :attr:`oracledb.defaults.osuser `, + :attr:`oracledb.defaults.program `, and + :attr:`oracledb.defaults.terminal ` to set + information about the driver name, machine name, operating system user, + program name, and terminal name respectively. The ``driver_name``, + ``machine``, ``osuser``, ``program``, and ``terminal`` parameters were also + added to :meth:`oracledb.connect()`, :meth:`oracledb.connect_async()`, + :meth:`oracledb.create_pool()`, and :meth:`oracledb.create_pool_async()` + (`issue 343 `__). +#) Added :meth:`oracledb.register_protocol()` to allow users to register a + function that will be called when a particular protocol is detected in a + 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 + 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 `__). +#) Added attribute :data:`PipelineOpResult.warning` to provide information + about any warning that was encountered during the execution of a pipeline + operation. +#) Added attribute :data:`PipelineOpResult.columns` to provide information + about any query column metadata returned from a pipeline operation. +#) Added support for setting the :ref:`edition ` when connecting to + Oracle Database. +#) Added support for Application Contexts, i.e. the ``appcontext`` parameter + is supported when connecting. +#) Fixed bug causing some pooled connections to be permanently marked as busy + and unavailable for reuse + (`issue 392 `__). +#) Fixed bug with error handling when calling :meth:`Connection.gettype()` for + a type that exists but on which the user has insufficient privileges to + view + (`issue 397 `__). +#) Fixed bug when calling :meth:`ConnectParams.parse_dsn_with_credentials()` + with an Easy Connect string containing a protocol. +#) Fixed bug when calling :meth:`Cursor.parse()` with autocommit enabled. +#) Fixed bug when parsing a :ref:`tnsnames.ora files ` file with + a connect descriptor containing an embedded comment. +#) Fixed bug when calling :meth:`AsyncConnection.run_pipeline()` with a DML + RETURNING statement that results in an error. +#) Fixed error message when a SQL statement is parsed containing a q-string + without a closing quote. +#) Fixed bug affecting Python interpreter shut down using connection pooling + in SQLAlchemy. Pooled connection shutdown now occurs separately from pool + destruction. + Thick Mode Changes ++++++++++++++++++ +#) Use `locale.getencoding() `__ with Python 3.11 and higher to determine the + encoding to use for the ``config_dir`` and ``lib_dir`` parameters to + :meth:`oracledb.init_oracle_client()`. Bytes are also accepted in which + case they will be used as is without any encoding + (`issue 255 `__). +#) Fixed bug preventing subscriptions from invoking the callbacks associated + with them + (`issue 409 `__). +#) Fixed bug affecting Application Continuity when older Oracle Client + libraries are used (`ODPI-C `__ dependency + update). + Common Changes ++++++++++++++ +#) Added support for returning the maximum identifier length allowed by the + database using the new property :data:`Connection.max_identifier_length` + (`issue 395 `__). +#) Improved type hints for cursors + (`issue 391 `__). +#) Improved error message when attempting to access attributes on a connection + before a connection has been established or a connection pool before it has + been created + (`issue 385 `__). +#) The variables saved with :meth:`Cursor.setinputsizes()` are now forgotten + when an exception is raised + (`issue 411 `__). +#) Fixed bug when calling :meth:`ConnectParams.set()` with a value of ``None`` + for the ``connectiontype`` and ``session_callback`` parameters. Previously, + any values set earlier would be improperly cleared and now they are + retained + (`issue 404 `__). +#) Improved test suite and documentation. + + +oracledb 2.4.1 (August 2024) +---------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Fixed bug when detecting in-band notification warnings while the connection + is being created or actively used + (`issue 383 `__). + + +oracledb 2.4.0 (August 2024) +---------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Added support for Oracle Database 23ai :ref:`statement pipelining + `. +#) Fixed bug resulting in a segfault when a closed cursor is bound as a REF + CURSOR + (`issue 368 `__). +#) Fixed bug resulting in an inability to connect to Oracle Database 23ai + instances which have fast authentication disabled. +#) Fixed error message when idle time is exceeded by a connection. The error + ``DPY-4033: the database closed the connection because the connection's + idle time has been exceeded`` is now raised when this situation is + detected. +#) Reworked connection string parser: + + - Fixed parsing an :ref:`Easy Connect ` string starting + with "`//`" (`issue 352 + `__). + - Fixed parsing an Easy Connect string with multiple hosts (a comma for + multiple addresses and a semicolon for multiple address lists). + - Fixed parsing an Easy Connect string with a static IPv6 address. + - Improved error when a connect descriptor parameter like DESCRIPTION or + ADDRESS incorrectly contains a simple value instead of nested values. + +#) Reworked :ref:`tnsnames.ora` file parser to handle multiple + aliases found on separate lines (`issue 362 + `__). + +Thick Mode Changes +++++++++++++++++++ + +#) Variables containing cursors, LOBs or DbObject values now return the same + instances when calling :meth:`Variable.getvalue()`, matching Thin mode + behavior. Previously, new instances were created for each call in Thick + mode. + +Common Changes +++++++++++++++ + +#) Added support for Python 3.13 and dropped support for Python 3.7. +#) Attribute :data:`ConnectionPool.getmode` is now one of the values of the + enumeration :ref:`connection pool get modes ` in order to be + consistent with the other uses of this attribute. +#) Error ``DPY-3027: binding a cursor from a different connection is not + supported`` is now raised when attempting to bind a cursor created on a + 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. + + +oracledb 2.3.0 (July 2024) +-------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Added support for :ref:`two-phase commits `. +#) Added support for columns of type BFILE. +#) When calling :meth:`ConnectionPool.acquire()` or + :meth:`AsyncConnectionPool.acquire()`, the connection pool ``mode`` + :data:`oracledb.POOL_GETMODE_TIMEDWAIT` now always honors the + ``wait_timeout`` value and the connection request will not additionally be + delayed by any internal network ping to the database (`issue 330 + `__). +#) Fixed bug when calling :meth:`oracledb.connect_async()` multiple times + concurrently + (`issue 353 `__). +#) Fixed bug in fetching dates with years less than 0 + (`issue 345 `__). + + +Thick Mode Changes +++++++++++++++++++ + +#) Eliminated memory leak when dequeing messages with JSON payloads + (`issue 346 `__). +#) An exception is now avoided if an error message is not correctly UTF-8 + encoded by the database. + +Common Changes +++++++++++++++ + +#) Added support for Oracle Database 23ai + :ref:`BINARY vector format `. +#) Replaced integer constants for + :ref:`connection authorization modes `, + :ref:`connection pool get modes `, + :ref:`connection pool purity constants ` and + :ref:`vector format constants ` with + `enumerations `__ in order to + provide a more useful ``repr()`` and improve type safety, among other + things. +#) The default value of the ``tcp_connect_timeout`` parameter was changed + from 60 seconds to 20 seconds. The default value of the + ``retry_delay`` parameter was changed from 0 seconds to 1 second. +#) Added parameter ``ssl_version`` to :meth:`oracledb.connect()` + :meth:`oracledb.connect_async()`, :meth:`oracledb.create_pool()`, and + :meth:`oracledb.create_pool_async()` methods in order to specify which TLS + version to use when establishing connections with the protocol "tcps". +#) Added parameter ``ping_timeout`` to methods :meth:`oracledb.create_pool()` + and :meth:`oracledb.create_pool_async()` with a default value of 5000 + milliseconds. This limits the amount of time that a call to + :meth:`~ConnectionPool.acquire()` will wait for a connection to respond to + any internal ping to the database before the connection is considered + unusable and a different connection is returned to the application. + Previously, a fixed timeout of 5000 milliseconds was used in Thick mode and + no explicit timeout was used in Thin mode. +#) Added support for maintainers to specify optional compilation arguments + when building python-oracledb. A new environment variable + ``PYO_COMPILE_ARGS`` can be set :ref:`before building `. +#) Improved detection of the signature used by output type handlers, in + particular those that that make use of ``__call__()``. +#) Python wheel package binaries for Linux on `PyPI + `__ are now stripped to reduce their + size. +#) Error ``DPY-2049: invalid flags for tpc_begin()`` is now raised when + invalid flags are passed to :meth:`Connection.tpc_begin()`. Previously, + ``TypeError`` or ``ORA-24759: invalid transaction start flags`` + was raised instead. +#) Error ``DPY-2050: invalid flags for tpc_end()`` is now raised when invalid + flags are passed to :meth:`Connection.tpc_end()`. Previously, ``TypeError`` + or ``DPI-1002: invalid OCI handle`` was raised instead. +#) Error ``DPY-3025: operation is not supported on BFILE LOBs`` is now raised + when operations are attempted on BFILE LOBs that are not permitted. + Previously, ``ORA-22275: invalid LOB locator specified`` was raised + instead. +#) Error ``DPY-3026: operation is only supported on BFILE LOBs`` is now raised + when operations are attempted on LOBs that are only supported by BFILE + LOBs. Previously, ``DPI-1002: invalid OCI handle`` was raised instead. +#) Error ``DPY-4005: timed out waiting for the connection pool to return a + connection`` is now raised consistently when using get mode + :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 + mode. +#) If both the ``sid`` and ``service_name`` parameters are specified to + :meth:`oracledb.makedsn()`, now only the ``service_name`` parameter is + used and the ``sid`` parameter is ignored. +#) Fixed bug in :meth:`ConnectParams.set()` where parameters found in a + connect string (like ``host`` and ``service_name``) would be ignored. +#) Fixed bug in :meth:`Connection.tpc_recover()` where the returned items were + not of the type returned by :meth:`Connection.xid()` as documented. +#) Internal changes to ensure that no circular imports occur. + + +oracledb 2.2.1 (May 2024) +------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Fixed bug when a :ref:`DbObject ` instance contains an attribute + of type ``SYS.XMLTYPE`` + (`issue 336 `__). +#) Fixed bug when fetching LOBs after an exception has been raised + (`issue 338 `__). +#) Fixed bug when a connect descriptor is used that doesn't define any + addresses + (`issue 339 `__). +#) Fixed bug in statement cache when the maximum number of cursors is unknown + due to the database not being open. +#) Fixed bug in handling redirect data with small SDU sizes. +#) Fixed bug with TLS renegotiation under some circumstances. +#) Adjusted handling of internal break/reset mechanism in order to avoid + potential hangs in some configurations under some circumstances. + + +oracledb 2.2.0 (May 2024) +------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Fixed bug in handling invisible columns with object type names containing + ``%ROWTYPE`` + (`issue 325 `__). +#) Fixed bug that would cause pooled connections to be marked checked out but + be unavailable for use permanently + (`issue 221 `__). +#) Fixed bug that would cause an internal error to be raised when attempting + to close a connection that has been forcibly closed by the database. +#) Internal change: further efforts to tighten code looking for the end of a + database request made to Oracle Database 23ai. + +Common Changes +++++++++++++++ + +#) Added support for Oracle Database 23ai columns of type :ref:`VECTOR + `. +#) Added support for columns of type INTERVAL YEAR TO MONTH which can be + represented in Python by instances of the new + :ref:`oracledb.IntervalYM ` class + (`issue 310 `__). +#) Added support for processing :ref:`tnsnames.ora files ` + containing ``IFILE`` directives + (`issue 311 `__). +#) Added support for getting a list of the network service names found in a + :ref:`tnsnames.ora ` file by adding the method + :meth:`ConnectParams.get_network_service_names()` + (`issue 313 `__). +#) Added support for iterating over :ref:`DbObject ` instances that + are collections + (`issue 314 `__). +#) Error ``ORA-24545: invalid value of POOL_BOUNDARY specified in connect + string`` is now raised consistently for both Thick and Thin modes. + Previously, Thin mode was raising the error + ``DPY-4030: invalid DRCP pool boundary {boundary}``. + + +oracledb 2.1.2 (April 2024) +--------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Fixed bug that prevented error ``ORA-01403: no data found`` from being + raised when executing a PL/SQL block + (`issue 321 `__). + +Common Changes +++++++++++++++ + +#) Fixed the internal regular expression used for parsing :ref:`Easy Connect + ` strings to avoid errors with connection string arguments + containing the ``/`` character. + + +oracledb 2.1.1 (March 2024) +--------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Fixed bug when calling :meth:`~Connection.gettype()` with an object type + name containing ``%ROWTYPE`` + (`issue 304 `__). +#) Error ``DPY-2048: the bind variable placeholder ":{name}" cannot be used + both before and after the RETURNING clause in a DML RETURNING statement`` + is now raised when the same bind variable placeholder name is used both + before and after the RETURNING clause in a + :ref:`DML RETURNING statement `. Previously, various + internal errors were raised. +#) Restored the error message raised when attempting to connect to Oracle + Database 11g. +#) Internal change: tightened up code looking for the end of a database + request. +#) Network packet output is now immediately flushed in order to avoid + losing output due to buffering when multiple threads are running. + + +oracledb 2.1.0 (March 2024) +--------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Oracle Database 23ai feature support: + + - Added support for + :ref:`implicit connection pooling with DRCP and PRCP `, + enabled by the new ``pool_boundary`` parameter to + :meth:`oracledb.connect()`, :meth:`oracledb.connect_async()`, + :meth:`oracledb.create_pool()` and :meth:`oracledb.create_pool_async()`. + - Improved the performance of connection creation by reducing the number of + round trips required for all connections. + - Added support for TCP Fast Open for applications connecting from within + the OCI Cloud network to Oracle Autonomous Database Serverless (ADB-S), + enabled by the new ``use_tcp_fast_open`` parameter to + :meth:`oracledb.connect()`, :meth:`oracledb.connect_async()`, + :meth:`oracledb.create_pool()` and :meth:`oracledb.create_pool_async()`. + +#) :ref:`asyncio ` changes: + + - Support for asyncio is no longer considered a pre-release. + - Internal change to improve handling of packets. + - Fixed bug when using :ref:`DRCP `. + - Fixed bug in processing metadata that spans multiple network packets. + - Fixed bug when connecting to a database using listener redirects + (`issue 285 `__). + +#) Added support for Easy Connect strings found in + :ref:`tnsnames.ora ` files. +#) Added support for writing UTF-8 encoded bytes to CLOB and NCLOB values and + writing strings to BLOB values in order to be consistent with what is done + for string variables. +#) User-defined errors raised by the database no longer display an error help + portal URL. +#) Fixed potential cursor issues when using :ref:`drcp`. +#) Fixed regression when using :ref:`IAM token authentication ` + (`issue 288 `__). +#) Fixed bug connecting to databases that are only mounted and not opened + (`issue 294 `__). +#) Fixed bug in identifying bind variables in SQL statements containing a + single line comment at the end of the statement. +#) Fixed bug in determining the list of attributes for PL/SQL collections. +#) Fixed bug in calculating the :data:`Connection.thin` attribute. +#) Fixed type declaration for the ``connectiontype`` parameter to + :meth:`oracledb.create_pool_async()` and the return value of + :meth:`AsyncConnectionPool.acquire()`. + + +Thick Mode Changes +++++++++++++++++++ + +#) Added support for internal use of JSON in SODA with Oracle Client 23. This + allows for seamless transfer of extended data types. +#) Fixed bug when calling :meth:`SodaDoc.getContent()` for SODA documents + that do not contain JSON. +#) Corrected support for Oracle Sharding. +#) Errors ``DPY-4011: the database or network closed the connection`` and + ``DPY-4024: call timeout of {timeout} ms exceeded`` now retain the original + error message raised by the Oracle Client library. + +Common Changes +++++++++++++++ + +#) Added a boolean property :data:`FetchInfo.is_oson` which is set when a + column has the check constraint ``IS JSON FORMAT OSON`` enabled. +#) Added methods :meth:`Connection.decode_oson()` and + :meth:`Connection.encode_oson()` to support fetching and inserting into + columns which have the check constraint ``IS JSON FORMAT OSON`` enabled. +#) Added class :ref:`oracledb.JsonId ` to represent JSON ID values + returned by SODA in Oracle Database 23.4 and later in the ``_id`` + attribute of documents stored in native collections. +#) Added support for columns of type VECTOR usable with a limited + availability release of Oracle Database 23. +#) Errors raised when calling :meth:`Cursor.executemany()` with PL/SQL now + have the :data:`oracledb._Error.offset` attribute populated with the last + iteration that succeeded + (`issue 283 `__). +#) A number of performance improvements were made. +#) Error ``DPY-2045: arraysize must be an integer greater than zero`` is now + raised when an invalid value is used for the attribute + :data:`Cursor.arraysize`. Previously, a variety of errors (``TypeError``, + ``OverflowError`` or ``ORA-03147: missing mandatory TTC field``) were + raised. +#) Error ``DPY-2016: variable array size of %d is too small (should be at + least %d)`` is now raised when :meth:`Cursor.executemany()` is called with + an integer number of iterations that is too large for the existing bind + variables. Previously, the python-oracledb Thin mode raised ``IndexError`` + and python-oracledb Thick mode raised + ``DPI-1018: array size of %d is too small``. +#) Error ``DPY-1001: not connected to database`` is now raised when an attempt + is made to perform an operation on a LOB using a closed connection. + Previously, the python-oracledb Thin mode raised an ``AttributeError`` + exception and python-oracledb Thick mode raised + ``DPI-1040: LOB was already closed``. +#) Fixed bug in :meth:`ConnectParams.get_connect_string()` when a value for + the connection parameter ``purity`` has been specified. +#) Fixed bug in :meth:`ConnectParams.set()` that would clear the + ``ssl_context``, ``appcontext``, ``shardingkey`` and ``supershardingkey`` + parameters if they were not included in the parameters. This also affected + calls to :meth:`oracledb.connect()` and :meth:`oracledb.create_pool()` that + made use of the DSN with credentials format. +#) The error ``DPY-2047: LOB amount must be greater than zero`` is now raised + when the ``amount`` parameter in :meth:`LOB.read()` is set to zero or + negative. +#) Fixed bug in the calculation of :data:`Cursor.rowcount` under some + circumstances. +#) Connection parameters that are strings now treat an empty string in the + same way as the value ``None``. + + +oracledb 2.0.1 (January 2024) +----------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Added support for using alternative event loop implementations such as + uvloop with :ref:`asyncio ` + (`issue 276 `__). +#) Added support for the `asynchronous context manager protocol + `__ on the + :ref:`AsyncCursor class ` as a convenience. +#) Fixed regression when connecting to a database using listener redirects + with either a :ref:`connection pool ` or using + :ref:`asyncio ` + (`issue 275 `__). +#) Fixed bug when an intermittent hang occurs on some versions of Oracle + Database while using :ref:`asyncio ` and the database raises an + error and output variables are present + (`issue 278 `__). +#) Fixed bug when fetch variables contain output converters and a query is + re-executed + (`issue 271 `__). +#) Corrected typing declaration for :meth:`oracledb.connect_async()`. +#) Internal change to ensure that connection pools are closed gracefully when + the main thread terminates. +#) Internal change to slightly improve performance of LOB reads and writes. + +Common Changes +++++++++++++++ + +#) Fixed regression which prevented a null value from being set on + :ref:`DbObject ` attributes or used as elements of collections + (`issue 273 `__). +#) Fixed regression from cx_Oracle which ignored the value of the + ``encoding_errors`` parameter when creating variables by calling the method + :meth:`Cursor.var()` + (`issue 279 `__). +#) Bumped minimum requirement of Cython to 3.0. + + +oracledb 2.0.0 (December 2023) +------------------------------ + +Thin Mode Changes ++++++++++++++++++ + +#) Added support for :ref:`concurrent programming with asyncio ` + (`issue 6 `__). +#) Added parameter :attr:`ConnectParams.sdu` for configuring the Session Data + Unit (SDU) size for sizing internal buffers used for tuning communication + with the database. The connection property :attr:`Connection.sdu` was also + added. +#) Added parameter :data:`ConnectParams.ssl_context` to modify the SSL context + used when connecting via TLS + (`issue 259 `__). +#) Added support for an Oracle Database 23ai JSON feature allowing field names + with more than 255 UTF-8 encoded bytes. +#) Added support for the ``FAILOVER`` clause in full connect descriptors. +#) Fixed bug in detecting the current time zone + (`issue 257 `__). +#) Fixed bug in handling database response in certain unusual circumstances. +#) Fixed bug in handling exceptions raised during connection establishment. +#) Fixed bug in identifying bind variables in SQL statements containing + multiple line comments with multiple asterisks before the closing slash. +#) A more meaningful error is raised when the wrong type of data is passed to + :meth:`LOB.write()`. +#) Internal change to support an Oracle Database 23ai JSON feature improving + JSON storage usage. +#) Internal change to ensure that all connections in a pool have been closed + gracefully before the pool is closed. +#) Internal changes to improve handling of the network protocol between + python-oracledb and Oracle Database. +#) Internal changes to improve handling of multiple address and description + lists in full connect descriptors. + +Thick Mode Changes +++++++++++++++++++ + +#) Fixed bug in return value of :meth:`SodaOperation.replaceOne()`. + +Common Changes +++++++++++++++ + +#) Dropped support for Python 3.6. +#) Desupported a number of parameters and attributes that were previously + deprecated. See :ref:`desupport notices<_desupported_2_0>` for details. +#) Added property :attr:`Cursor.warning` for database warnings (such as PL/SQL + compilation warnings) generated by calls to :meth:`Cursor.execute()` or + :meth:`Cursor.executemany()`. +#) Added property :attr:`Connection.warning` for warnings (such as the password + being in the grace period) generated during connection. +#) Added properties that provide information about the database: + :attr:`Connection.db_domain`, :attr:`Connection.db_name`, + :attr:`Connection.max_open_cursors`, :attr:`Connection.service_name` + and :attr:`Connection.transaction_in_progress`. +#) Added property :data:`Connection.proxy_user` to show the name of the user + which was used as a proxy when connecting (`issue 250 + `__). +#) 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. +#) 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 + ``SYS.XMLTYPE`` in the database. Previously the value of + :data:`FetchInfo.type_code` for data of this type was + :data:`~oracledb.DB_TYPE_LONG` in Thick mode and + :data:`~oracledb.DB_TYPE_OBJECT` in Thin mode. +#) Attribute and element values of :ref:`Oracle Object ` instances + that contain strings or bytes now have their maximum size constraints + checked. Errors ``DPY-2043`` (attributes) and ``DPY-2044`` (element values) + are now raised when constraints are violated. +#) Attribute and element values of :ref:`Oracle Object ` instances + that are numbers are now returned as integers if the precision and scale + allow for it. This is the same way that numbers are fetched from the + database + (`issue 99 `__). +#) Errors that have entries in the + :ref:`troubleshooting documentation ` now have links to + that documentation shown in the message text. +#) Fixed bug with binding boolean values with Oracle Database 23ai + (`issue 263 `__). +#) Fixed bug with getting unknown attributes from :ref:`Oracle Object + ` instances. +#) Error ``DPY-4029: errors in array DML exceed 65535`` is now raised when the + number of batch errors exceeds 65535 when calling + :meth:`Cursor.executemany()` with the parameter ``batcherrors`` set to the + value *True*. Note that in Thick mode this error is not raised unless the + number of batch errors is a multiple of 65536; instead, the number of batch + errors returned is modulo 65536 + (`issue 262 `__). +#) Black is now used to format Python code and ruff to lint Python code. + + +oracledb 1.4.2 (October 2023) +----------------------------- + +Thick Changes ++++++++++++++ + +#) Fixed bug resulting in a segfault on some platforms when using two-phase + commit. + +Common Changes +++++++++++++++ + +#) Pre-built binaries are now being created for Python 3.12 + (`issue 237 `__). + + +oracledb 1.4.1 (September 2023) +------------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Improved statement bind variable placeholder parser performance, handle + statements which use the `Alternative Quoting Mechanism + `__ + ('Q' strings), and fix some issues identifying bind variable placeholders + in embedded quotes and in JSON syntax. + +Thick Changes ++++++++++++++ + +#) Fixed error checking when getting or setting the connection pool parameters + ``ping_interval`` and ``soda_metadata_cache``. + +Common Changes +++++++++++++++ + +#) Fixed bug when calling :meth:`Cursor.execute()` or + :meth:`Cursor.executemany()` with missing bind data after calling + :meth:`Cursor.setinputsizes()` with at least one of the values supplied as + ``None`` + (`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 + an error. +#) Added missing ">" to ``repr()`` of :ref:`sodadb`. + + +oracledb 1.4.0 (August 2023) +---------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Added support for an Oracle Database 23ai feature that can improve the + performance of connection creation by reducing the number of round trips + required to create the second and subsequent connections to the same + database. +#) Added support for shrinking the connection pool back to the specified + minimum size when the pool is idle for :data:`ConnectionPool.timeout` + seconds. +#) Added support for growing the connection pool back to the minimum number of + connections after connections are killed or otherwise made unusable. +#) A default connection class is now generated when DRCP is used with a + connection pool and no connection class was specified when the pool was + created. The default connection class will be of the form ``DPY:`` followed + by a 16-byte unique identifier converted to base64 encoding. +#) Changed internal connection feature negotiation for more accurate Oracle + Database 23ai support. +#) Added support for sending a generated connection identifier to the + database used for tracing. An application specific prefix is prepended to + this value if specified via a new ``connection_id_prefix`` parameter when + creating standalone connections or connection pools. +#) Added URL to the Oracle Database Error Help Portal in Oracle Database + error messages similar to when Thick mode uses Oracle Client 23ai. +#) Added support for the ``ORA_SDTZ`` environment variable used to set the + session time zone used by the database. +#) Fixed bug when a dynamically sized connection pool is created with an + ``increment`` of zero and the pool needs to grow. +#) Fixed bug affecting connection reuse when connections were acquired from + the connection pool with a ``cclass`` different to the one used to + create the pool. +#) Fixed bug when a connection is discarded from the connection pool during + :meth:`ConnectionPool.acquire()` and the ping check fails due to the + connection being dead. +#) Fixed bug when an output type handler is used and the value of + :attr:`Cursor.prefetchrows` exceeds :attr:`Cursor.arraysize` + (`issue 173 `__). +#) Fixed bug when an Application Continuity replay context is returned during + connection to the database + (`issue 176 `__). +#) Fixed bug when socket is not closed immediately upon failure to establish a + connection to the database + (`issue 211 `__). + +Thick Mode Changes +++++++++++++++++++ + +#) Added function :meth:`SodaCollection.listIndexes()` for getting the indexes + on a SODA collection. +#) Added support for specifying if documents should be locked when fetched + from SODA collections. A new non-terminal method + :meth:`~SodaOperation.lock()` was added which requires Oracle Client + 21.3 or higher (or Oracle Client 19 from 19.11). +#) Relaxed restriction for end-to-end tracing string connection + attributes. These values can now be set to the value ``None`` which will be + treated the same as an empty string. +#) Fixed bug when using external authentication with an Easy Connect + connection string. +#) Fixed memory leak when accessing objects embedded within other objects. + +Common Changes +++++++++++++++ + +#) Use of Python 3.6 and 3.7 is deprecated and support for them will be + removed in a future release. A warning is issued when these versions are + used but otherwise they will continue to function as usual. The warning can + be suppressed by importing `warnings + `__ and adding a call like + ``warnings.filterwarnings(action='ignore', module="oracledb")`` + *before* importing ``oracledb``. +#) Added support for the :attr:`~Variable.outconverter` being called when a + null value is fetched from the database and the new parameter + ``convert_nulls`` to the method :meth:`Cursor.var()` is passed the value + ``True`` + (`issue 107 `__). +#) Replaced fixed 7-tuple for the cursor metadata found in + :data:`Cursor.description` with a class which provides additional + information such as the database object type and whether the column + contains JSON data. +#) Changed the signature for output type handlers to + ``handler(cursor, metadata)`` where the ``metadata`` parameter is a + :ref:`FetchInfo` object containing the same information found + in :data:`Cursor.description`. The original signature for output type + handlers is deprecated and will be removed in a future version. +#) 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 + ``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. +#) Added new property :attr:`Connection.instance_name` which provides the + Oracle Database instance name associated with the connection. This is the + same value as the SQL expression + ``sys_context('userenv', 'instance_name')``. +#) Added support for relational queries on the underlying tables of SODA + collections created in Oracle Database 23ai if they contain JSON documents + with embedded OIDs. +#) Automatically retry a query if the error ``ORA-00932: inconsistent data + types`` is raised (which can occur if a table or view is recreated with a + data type that is incompatible with the column's previous data type). +#) The ``repr()`` value of the DbObject class now shows the string "DbObject" + instead of the string "Object" for consistency with the name of the class + and the other ``repr()`` values for DbObjectType and DbObjectAttr. +#) Fixed bug when binding sequences other than lists and tuples + (`issue 205 `__). +#) Added support for using the Cython 3.0 release + (`issue 204 `__). +#) Improved test suite and documentation. + +oracledb 1.3.2 (June 2023) +-------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Fixed bug using :attr:`Cursor.arraysize` for tuning data fetches from REF + CURSORS. +#) Fixed bug connecting to databases with older 11g password verifiers + (`issue 189 `__). +#) Fixed bugs in the implementation of the statement cache. +#) Fixed bug which caused a cursor leak if an error was thrown while + processing the execution of a query. +#) Eliminated unneeded round trip when using token authentication to connect + to the database. +#) Fixed bug which could cause a redirect loop with improperly configured + listener redirects. +#) Fixed bug when executing PL/SQL with a large number of binds. +#) Fixed bug when using DRCP with Oracle Database 23ai. + +Thick Mode Changes +++++++++++++++++++ + +#) Fixed bug when using external authentication with a Net Service Name + connection string + (`issue 178 `__). +#) Fixed bug when using external authentication with an Easy Connect + connection string. + +Common Changes +++++++++++++++ + +#) When fetching rows from REF CURSORS, the cursor's + :attr:`~Cursor.prefetchrows` attribute is now ignored. Use + :attr:`Cursor.arraysize` for tuning these fetches. This change allows + consistency between Thin and Thick modes. + + +oracledb 1.3.1 (April 2023) +--------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Improved performance of regular expressions used for parsing SQL + (`issue 172 `__). +#) Fixed bug with Oracle Database 23ai when SQL is executed after first being + parsed. +#) Fixed bug when :data:`ConnectionPool.timeout` is not `None` when creating a + connection pool + (`issue 166 `__). +#) Fixed bug when a query is re-executed after an underlying table is dropped + and recreated, and the query select list contains LOBs or JSON data. +#) Fixed bug when warning message such as for impending password expiry is + encountered during connect + (`issue 171 `__). + +Common Changes +++++++++++++++ + +#) Improved test suite and samples. + + +oracledb 1.3.0 (March 2023) +--------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Added direct support for the Oracle Database 21c JSON data type, removing + the need to use an output type handler. +#) Added implementation for :data:`ConnectionPool.timeout` to allow pools to + shrink to ``min`` connections. +#) Added check to prevent adding too many elements to bounded database + collections. +#) Removed internally set fixed size for database collections. Collections of + any size supported by the database can now be created. +#) 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 + (`issue 144 `__). +#) Improved BOOLEAN handling. +#) Error ``DPY-6005: cannot connect to database`` is now raised for all + failures to connect to the database and the phrase ``cannot connect to + database`` is removed from all other error messages (since this can be + confusing when these errors are raised from + :meth:`ConnectParams.parse_connect_string()`). +#) Fixed bug when calling :meth:`Cursor.executemany()` with PL/SQL when the + size of the bound data increases on subsequent calls + (`issue 132 `__). +#) Fixed bug when binding data of type TIMESTAMP WITH TIME ZONE but with + zero fractional seconds. +#) Fixed bug with incorrect values of :data:`Cursor.rowcount` when fetching + data + (`issue 147 `__). +#) Fixed bug with SQL containing multibyte characters with certain database + character sets + (`issue 133 `__). +#) Fixed bug with ordering of binds in SQL when the database version is 12.1 + (`issue 135 `__). +#) Fixed bug with ordering of binds in PL/SQL when the bind variable may + potentially exceed the 32767 byte limit but the actual value bound does not + (`issue 146 `__). +#) Fixed bug connecting to an IPv6 address with IAM tokens. +#) Fixed bug determining RETURNING binds in a SQL statement when RETURNING and + INTO keywords are not separated by whitespace, but are separated by + parentheses. +#) The exception ``DPY-3022: named time zones are not supported in thin mode`` + is now raised when attempting to fetch data of type TIMESTAMP WITH TIME + ZONE when the time zone associated with the data is a named time zone. + Previously invalid data was returned + (`disc 131 `__). +#) Internal implementation changes: + + - Added internal support for prefetching the LOB size and chunk size, + thereby eliminating a :ref:`round-trip` when calling + :meth:`LOB.size()` and :meth:`LOB.getchunksize()`. + - Made the pool implementation LIFO to improve locality, reduce the number + 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. + - Removed unneeded packet for changing the password of the connected user. + + +Thick Mode Changes +++++++++++++++++++ + +#) Raise a more meaningful error when an unsupported type in a JSON value is + detected. +#) Added support for the "signed int", "signed long" and "decimal128" scalar + types in JSON (generally only seen when converting from MongoDB). +#) Defer raising an exception when calling :meth:`Connection.gettype()` + for a type containing an attribute or element with an unsupported data type + until the first attempt to reference the attribute or element with the + unsupported data type. +#) Fixed bug when attempting to create bequeath connections when the DSN + contains credentials. + +Common Changes +++++++++++++++ + +#) Improved type annotations. +#) 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 + 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 + ``OCI-22165: given index [{index}] must be in the range of [{min_index}] to + [{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`` + (`issue 128 `__). +#) Internal changes to ensure that errors taking place while raising + exceptions are handled more gracefully. + + +oracledb 1.2.2 (January 2023) +----------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Any exception raised while finding the operating system user for database + logging is now ignored (`issue 112 + `__). +#) Fixed bug when binding OUT a NULL boolean value. + (`issue 119 `__). +#) Fixed bug when getting a record type based on a table (%ROWTYPE) + (`issue 123 `__). +#) Fixed bug when using a `select * from table` query and columns are added to + the table + (`issue 125 `__). + +Thick Mode Changes +++++++++++++++++++ + +#) Fixed bug when attempting to create bequeath connections to a local + database + (`issue 114 `__). + +Common Changes +++++++++++++++ + +#) Fixed bug when attempting to populate an array variable with too many + elements. + + +oracledb 1.2.1 (December 2022) +------------------------------ + +Thin Mode Changes ++++++++++++++++++ + +#) Fixed bug determining RETURNING binds in a SQL statement when RETURNING and + INTO keywords are not separated by spaces, but are separated by other + whitespace characters + (`issue 104 `__). +#) Fixed bug determining bind variables when found between two comment blocks + (`issue 105 `__). + +Thick Mode Changes +++++++++++++++++++ + +#) Fixed bug creating a homogeneous connection pool with a proxy user + (`issue 101 `__). +#) Fixed bug closing a SODA document cursor explicitly (instead of simply + allowing it to be closed automatically when it goes out of scope). +#) Fixed bug when calling :meth:`Subscription.registerquery()` with bind + values. +#) Fixed bug that caused :data:`Message.dbname` to always be the value `None`. + +Common Changes +++++++++++++++ + +#) Corrected ``__repr__()`` of connections to include the actual class name + instead of a hard-coded ``oracledb``. + + +oracledb 1.2.0 (November 2022) +------------------------------ + +Thin Mode Changes ++++++++++++++++++ + +#) Added support for binding and fetching data of type + :data:`~oracledb.DB_TYPE_OBJECT`. Note that some of the error codes and + messages have changed as a result: DPY errors are raised instead of ones + specific to ODPI-C and OCI + (`issue 43 `__). +#) Added support for fetching SYS.XMLTYPE data as strings. Note that unlike + in Thick mode, fetching longer values does not require using + ``XMLTYPE.GETCLOBVAL()``. +#) Added support for using a wallet for one-way TLS connections, rather than + requiring OS recognition of certificates + (`issue 65 `__). +#) Added support for connecting to CMAN using ``(SOURCE_ROUTE=YES)`` in the + connect string + (`issue 81 `__). +#) Fixed bug when fetching nested cursors with more columns than the parent + cursor. +#) Fixed bug preventing a cursor from being reused after it was bound as a + REF CURSOR to a PL/SQL block that closes it. +#) Fixed bug preventing binding OUT data of type + :data:`~oracledb.DB_TYPE_UROWID` that exceeds 3950 bytes in length. +#) Fixed bug preventing correct parsing of connect descriptors with both + ``ADDRESS`` and ``ADDRESS_LIST`` components at the same level. +#) The complete connect string is now sent to the server instead of just the + actual components being used. This is important for some configurations. +#) Fixed bug resulting in an internal protocol error when handling database + responses. +#) Fixed bug when calling :meth:`Cursor.executemany()` with the `batcherrors` + parameter set to `True` multiple times with each call resulting in at least + one batch error. + +Thick Mode Changes +++++++++++++++++++ + +#) Connections acquired from a homogeneous pool now show the username and dsn + to which they are connected in their repr(). + +Common Changes +++++++++++++++ + +#) Added support for Python 3.11. +#) Added attribute :attr:`DbObjectType.package_name` which contains the name + of the package if the type is a PL/SQL type (otherwise, it will be `None`). +#) Added sample for loading data from a CSV file. +#) Improved test suite and documentation. + oracledb 1.1.1 (September 2022) ------------------------------- @@ -62,7 +1521,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 @@ -77,8 +1536,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. @@ -114,8 +1573,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 `__). @@ -181,7 +1640,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 @@ -217,16 +1676,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 @@ -252,7 +1711,7 @@ oracledb 1.0.0 (May 2022) errors when calling :meth:`ConnectionPool.acquire()` during pool growth. #) Connection pools in python-oracledb Thin mode support all :ref:`connection mode privileges `. -#) Added new :ref:`Two-phase commit ` functionality. +#) Added new :ref:`Two-phase commit ` functionality. #) Added :meth:`Connection.is_healthy()` to do a local check of a connection's health. #) Added a boolean parameter ``cache_statement`` to :meth:`Cursor.prepare()`, @@ -306,29 +1765,29 @@ cx_Oracle 8.2 (May 2021) `__. #) Threaded mode is now always enabled when creating connection pools with - :meth:`cx_Oracle.SessionPool()`. Any `threaded` parameter value is ignored. -#) Added :meth:`SessionPool.reconfigure()` to support pool reconfiguration. + ``cx_Oracle.SessionPool()``. Any `threaded` parameter value is ignored. +#) Added ``SessionPool.reconfigure()`` to support pool reconfiguration. This method provides the ability to change properties such as the size of existing pools instead of having to restart the application or create a new pool. -#) Added parameter `max_sessions_per_shard` to :meth:`cx_Oracle.SessionPool()` +#) Added parameter `max_sessions_per_shard` to ``cx_Oracle.SessionPool()`` to allow configuration of the maximum number of sessions per shard in the pool. In addition, the attribute - :data:`SessionPool.max_sessions_per_shard` was added in order to permit + ``SessionPool.max_sessions_per_shard`` was added in order to permit making adjustments after the pool has been created. They are usable when using Oracle Client version 18.3 and higher. -#) Added parameter `stmtcachesize` to :meth:`cx_Oracle.connect()` and - :meth:`cx_Oracle.SessionPool()` in order to permit specifying the size of +#) Added parameter `stmtcachesize` to ``cx_Oracle.connect()`` and + ``cx_Oracle.SessionPool()`` in order to permit specifying the size of the statement cache during the creation of pools and standalone connections. -#) Added parameter `ping_interval` to :meth:`cx_Oracle.SessionPool()` to +#) Added parameter `ping_interval` to ``cx_Oracle.SessionPool()`` to specify the ping interval when acquiring pooled connections. In addition, - the attribute :data:`SessionPool.ping_interval` was added in order to + the attribute ``SessionPool.ping_interval`` was added in order to permit making adjustments after the pool has been created. In previous cx_Oracle releases a fixed ping interval of 60 seconds was used. -#) Added parameter `soda_metadata_cache` to :meth:`cx_Oracle.SessionPool()` +#) Added parameter `soda_metadata_cache` to ``cx_Oracle.SessionPool()`` for :ref:`SODA metadata cache ` support. In addition, - the attribute :data:`SessionPool.soda_metadata_cache` was added in order to + the attribute ``SessionPool.soda_metadata_cache`` was added in order to permit making adjustments after the pool has been created. This feature significantly improves the performance of methods :meth:`SodaDatabase.createCollection()` (when not specifying a value for @@ -348,15 +1807,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, @@ -417,10 +1876,9 @@ cx_Oracle 8.0 (June 2020) #) Reworked type management to clarify and simplify code - Added :ref:`constants ` for all database types. The database - types :data:`cx_Oracle.DB_TYPE_BINARY_FLOAT`, - :data:`cx_Oracle.DB_TYPE_INTERVAL_YM`, - :data:`cx_Oracle.DB_TYPE_TIMESTAMP_LTZ` and - :data:`cx_Oracle.DB_TYPE_TIMESTAMP_TZ` are completely new. The other + types ``cx_Oracle.DB_TYPE_BINARY_FLOAT``, + ``cx_Oracle.DB_TYPE_INTERVAL_YM``, ``cx_Oracle.DB_TYPE_TIMESTAMP_LTZ`` + and ``cx_Oracle.DB_TYPE_TIMESTAMP_TZ`` are completely new. The other types were found in earlier releases under a different name. These types will be found in :data:`Cursor.description` and passed as the defaultType parameter to the :data:`Connection.outputtypehandler` and @@ -435,9 +1893,9 @@ cx_Oracle 8.0 (June 2020) new database type constants if the variable does not contain objects (previously it was None in that case). - The attribute :data:`~LOB.type` was added to LOB values. - - The attribute `type `_ was added to attributes of object types. - - The attribute `element_type `_ was added to object types. - - `Object types `_ now compare equal if they were created + - The attribute ``type`` was added to attributes of object types. + - The attribute ``element_type`` was added to object types. + - Object types now compare equal if they were created by the same connection or session pool and their schemas and names match. - All variables are now instances of the same class (previously each type was an instance of a separate variable type). The attribute @@ -446,7 +1904,7 @@ cx_Oracle 8.0 (June 2020) - The string representation of variables has changed to include the type in addition to the value. -#) Added function :meth:`cx_Oracle.init_oracle_client()` in order to enable +#) Added function ``cx_Oracle.init_oracle_client()`` in order to enable programmatic control of the initialization of the Oracle Client library. #) The default encoding for all character data is now UTF-8 and any character set specified in the environment variable ``NLS_LANG`` is ignored. @@ -498,8 +1956,8 @@ cx_Oracle 7.3 (December 2019) #) Added :attr:`support ` for returning the rowid of the last row modified by an operation on a cursor (or None if no row was modified). -#) Added support for setting the maxSessionsPerShard attribute when - :meth:`creating session pools `. +#) Added support for setting the ``maxSessionsPerShard`` attribute when + creating connection pools. #) Added check to ensure sharding key is specified when a super sharding key is specified. #) Improved error message when the Oracle Client library is loaded @@ -567,7 +2025,7 @@ cx_Oracle 7.2.2 (August 2019) :meth:`Subscription.registerquery()` with SQL that is not a SELECT statement. #) Eliminated segfault when a connection is closed after being created by a - call to :meth:`cx_Oracle.connect()` with the parameter ``cclass`` set to + call to ``cx_Oracle.connect()`` with the parameter ``cclass`` set to a non-empty string. #) Added user guide documentation. #) Updated default connect strings to use 19c and XE 18c defaults. @@ -609,7 +2067,7 @@ cx_Oracle 7.2 (July 2019) 18.5 and higher. #) Added support for setting LOB object attributes, as requested (`issue 299 `__). -#) Added mode :data:`cx_Oracle.DEFAULT_AUTH` as requested +#) Added mode ``cx_Oracle.DEFAULT_AUTH`` as requested (`issue 293 `__). #) Added support for using the LOB prefetch length indicator in order to reduce the number of round trips when fetching LOBs and then subsequently @@ -702,7 +2160,7 @@ cx_Oracle 7.1 (February 2019) version-3-1-january-21-2019>`__. #) Improved support for session tagging in session pools by allowing a session callback to be specified when creating a pool via - :meth:`cx_Oracle.SessionPool()`. Callbacks can be written in Python or in + ``cx_Oracle.SessionPool()``. Callbacks can be written in Python or in PL/SQL and can be used to improve performance by decreasing round trips to the database needed to set session state. Callbacks written in Python will be invoked for brand new connections (that have never been acquired from @@ -793,7 +2251,7 @@ cx_Oracle 7.0 (September 2018) dictionary, where the keys are the indices of the collection and the values are the elements of the collection. See function :meth:`Object.asdict()`. #) Added support for closing a session pool via the function - :meth:`SessionPool.close()`. Once closed, further attempts to use any + ``SessionPool.close()``. Once closed, further attempts to use any connection that was acquired from the pool will result in the error "DPI-1010: not connected". #) Added support for setting a LOB attribute of an object with a string or @@ -834,8 +2292,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 `__). @@ -856,7 +2314,7 @@ cx_Oracle 6.4 (July 2018) :meth:`Connection.subscribe()`. - Added support for subscribing to notifications when messages are available to dequeue in an AQ queue. The new constant - :data:`cx_Oracle.SUBSCR_NAMESPACE_AQ` should be passed to the namespace + ``cx_Oracle.SUBSCR_NAMESPACE_AQ`` should be passed to the namespace parameter of function :meth:`Connection.subscribe()` in order to get this functionality. Attributes :attr:`Message.queueName` and :attr:`Message.consumerName` will be populated in notification messages @@ -865,12 +2323,12 @@ cx_Oracle 6.4 (July 2018) callback know when the subscription that generated the notification is no longer registered with the database. - Added support for timed waits when acquiring a session from a session - pool. Use the new constant :data:`cx_Oracle.SPOOL_ATTRVAL_TIMEDWAIT` in - the parameter getmode to function :meth:`cx_Oracle.SessionPool` along - with the new parameter waitTimeout. + pool. Use the new constant ``cx_Oracle.SPOOL_ATTRVAL_TIMEDWAIT`` in + the parameter getmode to function ``cx_Oracle.SessionPool()`` along + with the new parameter ``waitTimeout``. - Added support for specifying the timeout and maximum lifetime session for session pools when they are created using function - :meth:`cx_Oracle.SessionPool`. Previously the pool had to be created + ``cx_Oracle.SessionPool()``. Previously the pool had to be created before these values could be changed. - Avoid memory leak when dequeuing from an empty queue. - Ensure that the row count for queries is reset to zero when the statement @@ -878,7 +2336,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 @@ -920,9 +2378,9 @@ cx_Oracle 6.3.1 (May 2018) - Ensure that before a statement is executed any buffers used for DML returning statements are reset. -#) Ensure that behavior with cx_Oracle.__future__.dml_ret_array_val not - set or False is the same as the behavior in cx_Oracle 6.2 - (`issue 176 `__). +#) Ensure that behavior with ``cx_Oracle.__future__.dml_ret_array_val`` not + set or False is the same as the behavior in cx_Oracle 6.2 (`issue 176 + `__). cx_Oracle 6.3 (April 2018) @@ -935,8 +2393,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 @@ -960,17 +2418,17 @@ cx_Oracle 6.3 (April 2018) #) Fixed support for getting the OUT values of bind variables bound to a DML Returning statement when calling the function :meth:`Cursor.executemany()`. - Note that the attribute dml_ret_array_val in :attr:`cx_Oracle.__future__` + Note that the attribute dml_ret_array_val in ``cx_Oracle.__future__`` must be set to True first. -#) Added support for binding integers and floats as cx_Oracle.NATIVE_FLOAT. -#) A :attr:`cx_Oracle._Error` object is now the value of all cx_Oracle +#) Added support for binding integers and floats as ``cx_Oracle.NATIVE_FLOAT``. +#) A ``cx_Oracle._Error`` object is now the value of all cx_Oracle exceptions raised by cx_Oracle. (`issue 51 `__). #) Added support for building cx_Oracle with a pre-compiled version of ODPI-C, as requested (`issue 103 `__). #) Default values are now provided for all parameters to - :meth:`cx_Oracle.SessionPool`. + ``cx_Oracle.SessionPool()``. #) Improved error message when an unsupported Oracle type is encountered. #) The Python GIL is now prevented from being held while performing a round trip for the call to get the attribute :attr:`Connection.version` @@ -1002,8 +2460,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 @@ -1027,7 +2485,7 @@ cx_Oracle 6.2 (March 2018) ``with`` code block controlled by the connection as a context manager, but in a backwards compatible way (`issue 113 `__). - See :data:`cx_Oracle.__future__` for more information. + See ``cx_Oracle.__future__`` for more information. #) Reorganized code to simplify continued maintenance and consolidate transformations to/from Python objects. #) Ensure that the number of elements in the array is not lost when the @@ -1103,9 +2561,9 @@ cx_Oracle 6.1 (December 2017) #) Ensure that the edition is passed through to the database when a session pool is created. #) Corrected handling of Python object references when an invalid keyword - parameter is passed to :meth:`cx_Oracle.SessionPool`. + parameter is passed to ``cx_Oracle.SessionPool()``. #) Corrected handling of :attr:`Connection.handle` and the handle parameter - to :meth:`cx_Oracle.connect` on Windows. + to ``cx_Oracle.connect()`` on Windows. #) Documentation improvements. #) Added test cases to the test suite. @@ -1120,7 +2578,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 @@ -1193,11 +2651,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 @@ -1269,7 +2727,7 @@ cx_Oracle 6.0 rc 1 (June 2017) `__). #) OCI requires that both encoding and nencoding have values or that both encoding and encoding do not have values. These parameters are used in - functions :meth:`cx_Oracle.connect` and :meth:`cx_Oracle.SessionPool`. The + functions ``cx_Oracle.connect()`` and ``cx_Oracle.SessionPool()``. The missing value is set to its default value if one of the values is set and the other is not (`issue 36 `__). @@ -1321,17 +2779,17 @@ cx_Oracle 6.0 beta 1 (April 2017) runtime cx_Oracle can adapt to Oracle Client 11.2, 12.1 or 12.2 libraries without needing to be rebuilt. This also means that wheels can now be produced and installed via pip. -#) Added attribute :attr:`SessionPool.stmtcachesize` to support getting and +#) Added attribute ``SessionPool.stmtcachesize`` to support getting and setting the default statement cache size for connections in the pool. #) Added attribute :attr:`Connection.dbop` to support setting the database operation that is to be monitored. #) Added attribute :attr:`Connection.handle` to facilitate testing the creation of a connection using a OCI service context handle. -#) Added parameters tag and matchanytag to the :meth:`cx_Oracle.connect` - and :meth:`SessionPool.acquire` methods and added parameters tag and retag - to the :meth:`SessionPool.release` method in order to support session +#) Added parameters tag and matchanytag to the ``cx_Oracle.connect()`` + and ``SessionPool.acquire()`` methods and added parameters tag and retag + to the ``SessionPool.release`` method in order to support session tagging. -#) Added parameter edition to the :meth:`cx_Oracle.SessionPool` method. +#) Added parameter edition to the ``cx_Oracle.SessionPool()`` method. #) Added support for `universal rowids `__. @@ -1341,7 +2799,7 @@ cx_Oracle 6.0 beta 1 (April 2017) #) Added attributes :attr:`Variable.actualElements` and :attr:`Variable.values` to variables. #) Added parameters region, sharding_key and super_sharding_key to the - :meth:`cx_Oracle.makedsn()` method to support connecting to a sharded + ``cx_Oracle.makedsn()`` method to support connecting to a sharded database (new in Oracle Database 12.2). #) Added support for smallint and float data types in Oracle objects, as `requested `__. @@ -1351,20 +2809,20 @@ cx_Oracle 6.0 beta 1 (April 2017) :meth:`Object.prev()`. #) If the environment variables NLS_LANG and NLS_NCHAR are being used, they must be set before the module is imported. Using the encoding and nencoding - parameters to the :meth:`cx_Oracle.connect` and - :meth:`cx_Oracle.SessionPool` methods is a simpler alternative to setting + parameters to the ``cx_Oracle.connect()`` and + ``cx_Oracle.SessionPool()`` methods is a simpler alternative to setting these environment variables. #) Removed restriction on fetching LOBs across round trips to the database (eliminates error "LOB variable no longer valid after subsequent fetch"). #) Removed requirement for specifying a maximum size when fetching LONG or LONG raw columns. This also allows CLOB, NCLOB, BLOB and BFILE columns to be fetched as strings or bytes without needing to specify a maximum size. -#) Dropped deprecated parameter twophase from the :meth:`cx_Oracle.connect` +#) Dropped deprecated parameter twophase from the ``cx_Oracle.connect()`` method. Applications should set the :attr:`Connection.internal_name` and :attr:`Connection.external_name` attributes instead to a value appropriate to the application. #) Dropped deprecated parameters action, module and clientinfo from the - :meth:`cx_Oracle.connect` method. The appcontext parameter should be used + ``cx_Oracle.connect()`` method. The appcontext parameter should be used instead as shown in this `sample `__. #) Dropped deprecated attribute numbersAsString from @@ -1392,9 +2850,8 @@ cx_Oracle 5.3 (March 2017) (available in Oracle 12.1) #) Added support for :attr:`Transaction Guard ` (available in Oracle 12.1). -#) Added support for setting the - :attr:`maximum lifetime ` of pool - connections (available in Oracle 12.1). +#) Added support for setting the maximum lifetime of pool connections + (available in Oracle 12.1). #) Added support for large row counts (larger than 2 ** 32, available in Oracle 12.1) #) Added support for :meth:`advanced queuing `. @@ -1422,9 +2879,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). @@ -1442,13 +2899,13 @@ cx_Oracle 5.3 (March 2017) more closely align with the PL/SQL implementation and prepare for sending notifications for AQ messages. The following changes were made: - - added constant :data:`~cx_Oracle.SUBSCR_QOS_BEST_EFFORT` to replace + - added constant ``cx_Oracle.SUBSCR_QOS_BEST_EFFORT`` to replace deprecated constant SUBSCR_CQ_QOS_BEST_EFFORT - - added constant :data:`~cx_Oracle.SUBSCR_QOS_QUERY` to replace + - added constant ``cx_Oracle.SUBSCR_QOS_QUERY`` to replace deprecated constant SUBSCR_CQ_QOS_QUERY - - added constant :data:`~cx_Oracle.SUBSCR_QOS_DEREG_NFY` to replace + - added constant ``cx_Oracle.SUBSCR_QOS_DEREG_NFY`` to replace deprecated constant SUBSCR_QOS_PURGE_ON_NTFN - - added constant :data:`~cx_Oracle.SUBSCR_QOS_ROWIDS` to replace parameter + - added constant ``cx_Oracle.SUBSCR_QOS_ROWIDS`` to replace parameter rowids for method :meth:`Connection.subscribe()` - deprecated parameter cqqos for method :meth:`Connection.subscribe()`. The qos parameter should be used instead. @@ -1468,8 +2925,9 @@ cx_Oracle 5.2.1 (January 2016) can be read in process dumps, for example). For those who would like to retain this feature, a subclass of Connection could be used to store the password. -#) Added optional parameter externalauth to SessionPool() which enables wallet - based or other external authentication mechanisms to be used. +#) Added optional parameter ``externalauth`` to ``cx_Oracle.SessionPool()`` + which enables wallet based or other external authentication mechanisms to + be used. #) Use the national character set encoding when required (when char set form is SQLCS_NCHAR); otherwise, the wrong encoding would be used if the environment variable ``NLS_NCHAR`` is set. @@ -1499,10 +2957,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 35aa13bb..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 - - 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 @@ -46,15 +43,19 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Homogeneous only - must use keyword arguments - Yes - must use keyword arguments - Yes - * - Connection Pool Connection Load Balancing (CLB) + * - Named Connection Pools (see :ref:`connpoolcache`) + - Yes + - Yes + - No + * - Connection Pool Connection Load Balancing (CLB) (see `Client-Side Load Balancing `__) - Yes - Yes - Yes - * - Connection Pool Runtime Load Balancing (RLB) + * - Connection Pool Runtime Load Balancing (RLB) (see `Runtime Connection Load Balancing `__) - No - Yes - Yes - * - Connection Pool draining + * - Connection Pool draining (see `Prepare Applications for Planned Maintenance `__) - Yes - Yes - Yes @@ -86,14 +87,22 @@ see :ref:`driverdiff` and :ref:`compatibility`. - No - Yes - Yes + * - Lightweight Directory Access Protocol (LDAP) connections (see :ref:`ldapconnections`) + - Yes - via a user function enabled with :meth:`oracledb.register_protocol()` + - Yes + - Yes * - Proxy connections (see :ref:`proxyauth`) - Yes - Yes - Yes + * - Socket Secure (SOCKS) Proxy connections + - No + - No + - No * - Connection mode privileges (see :ref:`connection-authorization-modes`) - Yes - - Yes - only :data:`~oracledb.AUTH_MODE_SYSDBA` is supported in Thick mode - - Yes + - Yes - only :data:`~oracledb.AUTH_MODE_SYSDBA` is supported + - Yes - only :data:`~oracledb.AUTH_MODE_SYSDBA` is supported * - Preliminary connections - No - Yes @@ -110,15 +119,15 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes - Yes - Yes - * - Oracle Sharded Databases (see :ref:`connsharding`) + * - Oracle Globally Distributed Database - previously known as Oracle Sharded Databases (see :ref:`connsharding`) - No - Yes - No TIMESTAMP support - Yes - No TIMESTAMP support - * - Oracle Database Native Network Encryption (see :ref:`nne`) - - No + * - Oracle Database Native Network Encryption (NNE) (see :ref:`nne`) + - No - use `TLS `__ instead - Yes - Yes - * - Connection pinging API + * - Connection health check APIs (see :meth:`~Connection.is_healthy()` and :meth:`~Connection.ping()`) - Yes - Yes - Yes @@ -134,22 +143,34 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Not applicable - Yes - Yes - * - Easy Connect Plus connection strings + * - Easy Connect connection strings (see :ref:`easyconnect`) - 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 - Yes * - Mutual TLS (mTLS) connections (see :ref:`twowaytls`) - - Yes - needs a PEM format wallet (see :ref:`createpem`) - Yes - Yes - * - Oracle Database Dedicated Servers, Shared Servers and Database Resident Connection Pooling (DRCP) + - Yes + * - Secure External Password Store (SEPS) wallet (e.g. wallets created by mkstore) + - No + - Yes + - Yes + * - Oracle Database Dedicated Servers, Shared Servers and :ref:`drcp`. + - Yes - Yes - Yes + * - Oracle Database 23ai Implicit Connection Pooling with :ref:`DRCP ` and PRCP (see :ref:`implicitconnpool`) - Yes + - Yes + - No * - Multitenant Databases - Yes - Yes @@ -167,18 +188,18 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes - Yes * - Edition Based Redefinition (EBR) (see :ref:`ebr`) - - No - not at connect time. ALTER SESSION can be used. + - Yes - Yes - Yes * - SQL execution (see :ref:`sqlexecution`) - - Yes - bind and fetch all types except BFILE, OBJECT, and JSON + - Yes - Yes - Yes * - PL/SQL execution (see :ref:`plsqlexecution`) - Yes for scalar types. Yes for collection types using array interface. - Yes - Yes - * - Simple Oracle Document Access (SODA) API (:ref:`SODA `) + * - Simple Oracle Document Access (SODA) API (see :ref:`SODA `) - No - Yes - Yes @@ -191,26 +212,26 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes - Yes * - SQL and PL/SQL type and collections (see :ref:`fetchobjects`) - - No - Yes - Yes - * - Query column metadata - Yes + * - Query column metadata (see :ref:`querymetadata`) - Yes - Yes - * - Client character set support - - UTF-8 - see :ref:`globalization` + - Yes + * - Client character set support (see :ref:`globalization`) + - UTF-8 - UTF-8 - Yes - can use Python encodings. Default in 8.0 is UTF-8 - * - Oracle Globalization support - - No - All NLS environment variables are ignored. Use Python globalization support instead - - Yes - NLS environment variables are respected except character set in NLS_LANG - - Yes - NLS environment variables are respected except character set in NLS_LANG - * - Row prefetching on first query execute.(see :attr:`prefetchrows`) - - Yes - - Yes - - Yes - * - Array fetching for queries (see :attr:`arraysize`) + * - Globalization support (see :ref:`globalization`) + - Yes - via Python globalization support + - Yes - Oracle Database NLS environment variables are respected, excluding the character set in NLS_LANG + - Yes - Oracle Database NLS environment variables are respected, excluding the character set in NLS_LANG + * - Row prefetching on first query execute (see :ref:`tuningfetch`) + - Yes - unless the row contains LOBs or similar types + - Yes - unless the row contains LOBs or similar types + - Yes - unless the row contains LOBs or similar types + * - Array fetching for queries (see :ref:`tuningfetch`) - Yes - Yes - Yes @@ -222,20 +243,24 @@ see :ref:`driverdiff` and :ref:`compatibility`. - No - Yes - Yes + * - Oracle Database 23ai JSON-Relational Duality Views (see :ref:`jsondualityviews`) + - Yes + - Yes + - No * - Continuous Query Notification (CQN) (see :ref:`cqn`) - 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`) @@ -263,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) @@ -274,104 +299,56 @@ see :ref:`driverdiff` and :ref:`compatibility`. - No - Yes - Yes - * - End-to-end monitoring and tracing attributes (see :ref:`tracingsql`) - - Yes + * - Concurrent programming with asyncio (see :ref:`concurrentprogramming`) - Yes - - Yes - * - Automatic Diagnostic Repository (ADR) - No - - Yes - - Yes - * - Java Debug Wire Protocol for debugging PL/SQL (see :ref:`jdwp`) - - Yes - - Yes - - Yes - * - Two-phase Commit (TPC) - No - - Yes - improved support (see :ref:`tcp`) - - Yes - limited support - * - REF CURSORs and Nested Cursors - - Yes - - Yes - - Yes - * - Pipelined tables - - Yes - - Yes + * - Oracle Database 23ai Pipelining (see :ref:`pipelining`) - Yes - * - Implicit Result Sets - - Yes - - Yes - - Yes - * - Application Contexts - No - - Yes - - Yes - * - Persistent and Temporary LOBs - - Yes - - Yes - - Yes - * - LOB prefetching - No - - No - does have LOB length prefetch - - No - does have LOB length prefetch - * - LOB locator operations such as trim - - Yes - - Yes - - Yes - * - CHAR, VARCHAR2, NUMBER, FLOAT, DATE, and LONG data types - - Yes - - Yes - - Yes - * - BLOB and CLOB data types + * - End-to-end monitoring and tracing attributes (see :ref:`tracingsql`) - Yes - Yes - Yes - * - BINARY_DOUBLE and BINARY_FLOAT data types + * - Automatic Diagnostic Repository (ADR) (see `About Fault Diagnosability in OCI `__) + - No - Yes - Yes + * - Java Debug Wire Protocol for debugging PL/SQL (see :ref:`jdwp`) - Yes - * - RAW and LONG RAW data types - Yes - Yes + * - Two-phase Commit (TPC) (see :ref:`tpc`) - Yes - * - INTERVAL DAY TO SECOND data type (see :data:`~oracledb.DB_TYPE_INTERVAL_DS`) - Yes + - Yes - limited support + * - REF CURSORs and Nested Cursors - Yes - Yes - * - INTERVAL YEAR TO MONTH data type (see :data:`~oracledb.DB_TYPE_INTERVAL_YM`) - - No - - No - - No - * - Oracle 12c JSON - Yes + * - Pipelined tables - Yes - Yes - * - Oracle 21c JSON data type (see :data:`~oracledb.DB_TYPE_JSON`) - - No - can fetch with an output type handler, see :ref:`Fetching JSON Differences ` - Yes + * - Implicit Result Sets - Yes - * - ROWID, UROWID data types - Yes - Yes + * - Application Contexts (see :ref:`appcontext`) - Yes - * - TIMESTAMP, TIMESTAMP WITH TIME ZONE, TIMESTAMP WITH LOCAL TIME ZONE data types - Yes - Yes + * - Persistent and Temporary LOBs - Yes - * - NCHAR, NVARCHAR2, NCLOB data types - Yes - Yes + * - LOB length prefetching - Yes - * - PL/SQL data types BOOLEAN, PLS_INTEGER and BINARY_INTEGER - Yes - Yes + * - LOB locator operations such as trim - Yes - * - XMLType data type (see :ref:`xmldatatype`) - - No - - No - - No - * - BFILE data type (see :data:`~oracledb.DB_TYPE_BFILE`) - - No - Yes - Yes @@ -381,211 +358,151 @@ Supported Oracle Database Data Types ==================================== The following table lists the Oracle Database types that are supported in the -python-oracledb driver. See `Oracle Database Types -`__ and `PL/SQL Types `__. The python-oracledb constant shown is the common one. In some -python-oracledb APIs you may use other types, for example when binding numeric -values. +python-oracledb driver. See `Oracle Database Types `__ +and `PL/SQL Types `__. The python-oracledb constant shown +is the common one. In some python-oracledb APIs you may use other types, for +example when binding numeric values. .. list-table-with-summary:: Oracle Database Data Types Supported :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 indicates if the type is supported in python-oracledb. + :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 - - Supported in python-oracledb - Supported Python Types + - Notes * - VARCHAR2 - - DB_TYPE_VARCHAR - - Yes + - :data:`~oracledb.DB_TYPE_VARCHAR` - bytes, str + - No relevant notes * - NVARCHAR2 - - DB_TYPE_NVARCHAR - - Yes + - :data:`~oracledb.DB_TYPE_NVARCHAR` - bytes, str + - No relevant notes * - NUMBER, FLOAT - - DB_TYPE_NUMBER - - Yes + - :data:`~oracledb.DB_TYPE_NUMBER` - bool, int, float, decimal.Decimal + - No relevant notes * - DATE - - DB_TYPE_DATE - - Yes + - :data:`~oracledb.DB_TYPE_DATE` - datetime.date, datetime.datetime - * - BOOLEAN (PL/SQL) - - DB_TYPE_BOOLEAN - - Yes - - ANY (converted to bool) + - No relevant notes + * - BOOLEAN (PL/SQL and Oracle Database 23ai SQL) + - :data:`~oracledb.DB_TYPE_BOOLEAN` + - Any type convertible to bool + - No relevant notes * - BINARY_DOUBLE - - DB_TYPE_BINARY_DOUBLE - - Yes + - :data:`~oracledb.DB_TYPE_BINARY_DOUBLE` - bool, int, float, decimal.Decimal + - No relevant notes * - BINARY_FLOAT - - DB_TYPE_BINARY_FLOAT - - Yes + - :data:`~oracledb.DB_TYPE_BINARY_FLOAT` - bool, int, float, decimal.Decimal + - No relevant notes * - TIMESTAMP - - DB_TYPE_TIMESTAMP - - Yes + - :data:`~oracledb.DB_TYPE_TIMESTAMP` - datetime.date, datetime.datetime + - No relevant notes * - TIMESTAMP WITH TIME ZONE - - DB_TYPE_TIMESTAMP_TZ - - Yes + - :data:`~oracledb.DB_TYPE_TIMESTAMP_TZ` - datetime.date, datetime.datetime + - No relevant notes * - TIMESTAMP WITH LOCAL TIME ZONE - - DB_TYPE_TIMESTAMP_LTZ - - Yes + - :data:`~oracledb.DB_TYPE_TIMESTAMP_LTZ` - datetime.date, datetime.datetime + - No relevant notes * - INTERVAL YEAR TO MONTH - - DB_TYPE_INTERVAL_YM - - Not supported in python-oracledb - - cannot be set + - :data:`~oracledb.DB_TYPE_INTERVAL_YM` + - :ref:`oracledb.IntervalYM ` + - No relevant notes * - INTERVAL DAY TO SECOND - - DB_TYPE_INTERVAL_DS - - Yes + - :data:`~oracledb.DB_TYPE_INTERVAL_DS` - datetime.timedelta + - No relevant notes * - RAW - - DB_TYPE_RAW - - Yes + - :data:`~oracledb.DB_TYPE_RAW` - bytes, str + - No relevant notes * - LONG - - DB_TYPE_LONG - - Yes + - :data:`~oracledb.DB_TYPE_LONG` - bytes, str + - No relevant notes * - LONG RAW - - DB_TYPE_LONG_RAW - - Yes + - :data:`~oracledb.DB_TYPE_LONG_RAW` - bytes, str + - No relevant notes * - ROWID - - DB_TYPE_ROWID - - Yes + - :data:`~oracledb.DB_TYPE_ROWID` - bytes, str + - No relevant notes * - UROWID - - DB_TYPE_ROWID, DB_TYPE_UROWID (only supported in python-oracledb Thin mode) - - Yes. May show DB_TYPE_UROWID in metadata. See :ref:`Query Metadata Differences `. + - :data:`~oracledb.DB_TYPE_ROWID`, :data:`~oracledb.DB_TYPE_UROWID` (only supported in python-oracledb Thin mode) - bytes, str + - May show :data:`~oracledb.DB_TYPE_UROWID` in metadata. See :ref:`Query Metadata Differences `. * - CHAR - - DB_TYPE_CHAR - - Yes + - :data:`~oracledb.DB_TYPE_CHAR` - bytes, str + - No relevant notes * - BLOB - - DB_TYPE_BLOB - - Yes - - BLOB, bytes, str + - :data:`~oracledb.DB_TYPE_BLOB` + - :ref:`oracledb.LOB `, bytes, str + - No relevant notes * - CLOB - - DB_TYPE_CLOB - - Yes - - CLOB, bytes, str + - :data:`~oracledb.DB_TYPE_CLOB` + - :ref:`oracledb.LOB `, bytes, str + - No relevant notes * - NCHAR - - DB_TYPE_NCHAR - - Yes + - :data:`~oracledb.DB_TYPE_NCHAR` - bytes, str + - No relevant notes * - NCLOB - - DB_TYPE_NCLOB - - Yes - - NCLOB, bytes, str + - :data:`~oracledb.DB_TYPE_NCLOB`, :data:`~oracledb.DB_TYPE_LONG_NVARCHAR` (if fetching NCLOB as a string) + - :ref:`oracledb.LOB `, bytes, str + - No relevant notes * - BFILE - - DB_TYPE_BFILE - - Not supported in python-oracledb Thin mode - - cannot be set + - :data:`~oracledb.DB_TYPE_BFILE` + - :ref:`oracledb.LOB `, bytes + - Can fetch a BFILE object and insert that object in a table. Cannot create BFILE objects. * - JSON - - DB_TYPE_JSON - - Yes. In python-oracledb Thin mode use an output type handler to fetch this Oracle Database 21c data type. See :ref:`jsondatatype`. - - ANY (converted) + - :data:`~oracledb.DB_TYPE_JSON` + - Any type convertible to Oracle JSON + - No relevant notes * - REF CURSOR (PL/SQL OR nested cursor) - - DB_TYPE_CURSOR - - Yes - - CURSOR + - :data:`~oracledb.DB_TYPE_CURSOR` + - :ref:`oracledb.Cursor ` + - No relevant notes * - PLS_INTEGER - - DB_TYPE_BINARY_INTEGER - - Yes + - :data:`~oracledb.DB_TYPE_BINARY_INTEGER` - bool, int, float, decimal.Decimal + - No relevant notes * - BINARY_INTEGER - - DB_TYPE_BINARY_INTEGER - - Yes + - :data:`~oracledb.DB_TYPE_BINARY_INTEGER` - 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 - - n/a - - Not supported in python-oracledb. Use ``xmltype.getclobval()`` to fetch. - - n/a + - :data:`~oracledb.DB_TYPE_XMLTYPE` + - 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) - - DB_TYPE_OBJECT - - Not supported in python-oracledb Thin mode + - :data:`~oracledb.DB_TYPE_OBJECT` - OBJECT of specific type + - No relevant notes + * - VECTOR + - :data:`~oracledb.DB_TYPE_VECTOR` + - 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. - -.. Python Types supported for each Oracle Database Type are shown below... list-table-with-summary:: Oracle Database Types Supported - :header-rows: 1 - :align: center - :summary: The first column displays the Oracle Database type. The second column displays the Python types that are supported for each of the database types. - - * - Oracle Database Type - - Python Types supported - * - DB_TYPE_BFILE - - cannot be set - * - DB_TYPE_BINARY_DOUBLE - - bool, int, float, decimal.Decimal - * - DB_TYPE_BINARY_FLOAT - - bool, int, float, decimal.Decimal - * - DB_TYPE_BINARY_INTEGER - - bool, int, float, decimal.Decimal - * - DB_TYPE_BLOB - - BLOB, bytes, str - * - DB_TYPE_BOOLEAN - - ANY (converted to bool) - * - DB_TYPE_CHAR - - bytes, str - * - DB_TYPE_CLOB - - CLOB, bytes, str - * - DB_TYPE_CURSOR - - CURSOR - * - DB_TYPE_DATE - - datetime.date, datetime.datetime - * - DB_TYPE_INTERVAL_DS - - datetime.timedelta - * - DB_TYPE_INTERVAL_YM - - cannot be set - * - DB_TYPE_JSON - - ANY (converted) - * - DB_TYPE_LONG - - bytes, str - * - DB_TYPE_LONG_NVARCHAR - - bytes, str - * - DB_TYPE_LONG_RAW - - bytes, str - * - DB_TYPE_NCHAR - - bytes, str - * - DB_TYPE_NCLOB - - NCLOB, bytes, str - * - DB_TYPE_NUMBER - - bool, int, float, decimal.Decimal - * - DB_TYPE_NVARCHAR - - bytes, str - * - DB_TYPE_OBJECT - - OBJECT of specific type - * - DB_TYPE_RAW - - bytes, str - * - DB_TYPE_ROWID - - bytes, str - * - DB_TYPE_TIMESTAMP - - datetime.date, datetime.datetime - * - DB_TYPE_TIMESTAMP_LTZ - - datetime.date, datetime.datetime - * - DB_TYPE_TIMESTAMP_TZ - - datetime.date, datetime.datetime - * - DB_TYPE_UROWID - - bytes, str - * - DB_TYPE_VARCHAR - - bytes, str +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 476f34ba..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,110 +73,6 @@ In the python-oracledb Thin mode: See :ref:`optnetfiles` and :ref:`optclientfiles` for more information. -.. _diffconnstr: - -Connection Strings ------------------- - -The python-oracledb Thin mode accepts connection strings in the same formats as -the Oracle Client libraries used by Thick mode does, but not all Oracle Net -keywords will be supported. - -The following table lists the parameters that are recognized in Thin mode -either in Easy Connect Strings or in Full Connect Descriptor Strings that are -either explicitly passed or referred to by a ``tnsnames.ora`` alias. All -unrecognized parameters are ignored. The connection parameters shown can be -used in :meth:`oracledb.connect()`, :meth:`oracledb.create_pool()`, -: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 - - - * - EXPIRE_TIME - - expire_time - - - * - HTTPS_PROXY - - https_proxy - - - * - HTTPS_PROXY_PORT - - https_proxy_port - - - * - RETRY_COUNT - - retry_count - - - * - RETRY_DELAY - - retry_delay - - - * - TRANSPORT_CONNECT_TIMEOUT - - tcp_connect_timeout - - - * - POOL_CONNECTION_CLASS - - cclass - - - * - POOL_PURITY - - purity - - - * - SERVICE_NAME - - service_name - - - * - SID - - sid - - - * - PORT - - port - - - * - PROTOCOL - - protocol - - - -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. 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. - -The ``Session Data Unit (SDU)`` connect descriptor option that is used to tune -network transfers is not supported in python-oracledb Thin mode. The value is -hard-coded as 8 KB. In python-oracledb Thick mode, the SDU connect descriptor -option and equivalent ``sqlnet.ora`` setting are used. - -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 -------------------------- @@ -190,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 @@ -209,19 +105,31 @@ 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 + +or:: -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 the error:: + DPY-4011: the database or network closed the connection + +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 =========================================================== @@ -233,14 +141,14 @@ the recommended way to create a connection pool. The use of the equivalent The :func:`~oracledb.create_pool()` method in the python-oracledb Thin mode differs from the python-oracledb Thick mode in the following ways: -* Not all the parameters of the :func:`oracledb.create_pool()` method are applicable - to both python-oracledb modes. Each mode ignores unrecognized parameters. - The parameters that are ignored in Thin mode include ``events``, ``tag``, - ``matchanytag``, ``appcontext``, ``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. +* Not all the parameters of the :func:`oracledb.create_pool()` method are + applicable to both python-oracledb modes. Each mode ignores unrecognized + parameters. The parameters that are ignored in Thin mode include ``events``, + ``tag``, ``matchanytag``, ``shardingkey``, ``supershardingkey``, and + ``handle`` parameters. The parameters that are ignored in the Thick mode + include ``wallet_password``, ``disable_oob``, and ``debug_jdwp`` parameters. -* 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 @@ -252,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` @@ -269,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`. @@ -281,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: @@ -305,6 +210,22 @@ and UROWID database types. In python-oracledb Thick and Thin modes, comparison w the type ``oracledb.ROWID`` (defined in the Python DB API) will match both ROWID and UROWID database types. +.. _implicitresultsdiff: + +Implicit Results in Thin and Thick Modes +======================================== + +In python-oracledb Thick mode, the parent cursor that is used to get the +:ref:`implicit results ` must remain open until all of the +implicit result sets have been fetched or until the application no longer +requires them. Closing the parent cursor before all the implicit result sets +have been fetched will result in the automatic closure of the implicit result +set cursors. + +In python-oracledb Thin mode, there is no requirement to leave the parent +cursor open when fetching implicit result sets. The parent cursor and implicit +cursors are independently handled in Thin mode. + .. _stmtcaching: Statement Caching in Thin and Thick Modes @@ -317,15 +238,6 @@ not supported in the Oracle Client libraries that are used in python-oracledb Thick mode. Note changing the type of bind variables for the same SQL text is inappropriate and gives indeterminate results in both modes. -.. _fetchJSON: - -Fetching JSON in Thin and Thick Modes -===================================== - -The python-oracledb Thin mode does not natively handle the Oracle Database 21c -JSON data type but a type handler can be used when fetching the type, see -:ref:`jsondatatype`. - Error Handling in Thin and Thick Modes ====================================== @@ -335,9 +247,8 @@ The python-oracledb Thin and Thick modes handle some errors differently. See Globalization in Thin and Thick Modes ===================================== -All NLS environment variables, and the ``ORA_SDTZ`` and ``ORA_TZFILE`` -environment variables, are ignored by the python-oracledb Thin mode. Use -Python's capabilities instead. +All NLS environment variables, and the ``ORA_TZFILE`` environment variable, are +ignored by the python-oracledb Thin mode. Use Python's capabilities instead. The python-oracledb Thin mode can only use NCHAR, NVARCHAR2, and NCLOB data when Oracle Database's secondary character set is AL16UTF16. diff --git a/doc/src/user_guide/appendix_c.rst b/doc/src/user_guide/appendix_c.rst index 78d9e396..0d8fa3d8 100644 --- a/doc/src/user_guide/appendix_c.rst +++ b/doc/src/user_guide/appendix_c.rst @@ -1,356 +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 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 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 ``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 deprecated and ignored: - - - ``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. - -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. - -See :ref:`connattrs` for more information. - -Pooling Differences from cx_Oracle ----------------------------------- - -It is recommended to use the new equivalent :ref:`ConnectionPool Object -` instead of the 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 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 ``sqlnet.ora`` - settings. - -- 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 constant - has been improved. Old names like ``SPOOL_ATTRVAL_NOWAIT`` can be used but are - now deprecated. - -- A new optional parameter ``params`` of type :ref:`PoolParams ` - can be used to encapsulate connection properties. See :ref:`usingconnparams` - for more information. - -- The ``encoding`` and ``decoding`` 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. - -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 deprecated 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. - -Advanced Queuing (AQ) Differences from cx_Oracle ------------------------------------------------- - -The old Advanced Queuing (AQ) API is not available in python-oracledb since it was -deprecated in cx_Oracle 7.2. Use the :ref:`new Advanced Queuing (AQ) `. -Note that AQ is only available in the Thick mode. - -Replace: - -- :meth:`Connection.deq()` with :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` -- :meth:`Connection.deqoptions()` with attribute :attr:`Queue.deqoptions` -- :meth:`Connection.enq()` with :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` -- :meth:`Connection.deqoptions()` with attribute :attr:`Queue.deqoptions` - -The AQ feature in the python-oracledb driver differs from cx_Oracle as follows: - -- 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 with the exceptions shown below. - -Note that the python-oracledb driver error messages can vary between Thin and -Thick modes. See :ref:`errorhandling`. - -ConnectionPool.acquire() Message Differences -++++++++++++++++++++++++++++++++++++++++++++ - -:meth:`ConnectionPool.acquire()` ORA errors will be mapped to DPY errors. For -example:: - - DPY-4005: timed out waiting for the connection pool to return a connection - -replaces the cx_Oracle 8.3 error:: - - ORA-24459: OCISessionGet() timed out waiting for pool to create new connections - -Dead Connection Detection and Timeout Message Differences -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -Application code which detects connection failures or statement execution -timeouts will need to check for new errors, DPY-4011 and DPY-4024 respectively. -The error DPY-1001 is returned if an already dead connection is attempted to be -used. - -The new Error object attribute :attr:`~oracledb._Error.full_code` may be useful -for checking the error code. - -Example error messages are: - -* Scenario 1: An already closed or dead connection was attempted to be used. - - python-oracledb Thin Error:: - - DPY-1001: not connected to database - - python-oracledb Thick Error:: - - DPY-1001: not connected to database - - cx_Oracle Error:: - - not connected - -* Scenario 2: The database side of the connection was terminated while the - connection was being used. - - python-oracledb Thin Error:: - - DPY-4011: the database or network closed the connection - - python-oracledb Thick Error:: - - DPY-4011: the database or network closed the connection - DPI-1080: connection was closed by ORA-%d - - cx_Oracle Error:: - - DPI-1080: connection was closed by ORA-%d - -* Scenario 3: Statement execution exceeded the :attr:`connection.call_timeout` - value. - - python-oracledb Thin Error:: - - DPY-4024: call timeout of {timeout} ms exceeded - - python-oracledb Thick Error:: - - DPY-4024: call timeout of {timeout} ms exceeded - DPI-1067: call timeout of %u ms exceeded with ORA-%d - - cx_Oracle Error:: - - DPI-1067: call timeout of %u ms exceeded with ORA-%d +The python-oracledb driver is the renamed, major version successor to cx_Oracle +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 -- 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:: + See :ref:`installation` for details. - python -m pip install oracledb +- 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. - See :ref:`driverdiff`. + 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. -- 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. +- 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`. -- python-oracledb can be used in SQLAlchemy, Django, Pandas, and other - frameworks and Object-relational Mappers (ORMs). Until they add native - support, you can override the use of cx_Oracle with a few lines of code. See - :ref:`frameworks`. + Examples can be found in the `GitHub samples directory + `__. A basic + example is: + + .. code-block:: python + + import oracledb + import getpass + + pw = getpass.getpass(f"Enter password for hr@localhost/orclpdb: ") + + 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). 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 @@ -358,39 +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") + connection = oracledb.connect("scott", pw, "localhost/orclpdb") -- The python-oracledb Thin mode ignores all NLS environment variables. It also - ignores ``ORA_SDTZ`` and ``ORA_TZFILE`` environment variables. Thick mode does use - these variables. See :ref:`globalization` for alternatives. +- 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 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. +- Some previously deprecated features are no longer available. See + :ref:`deprecations`. - Only python-oracledb Thick mode will read ``sqlnet.ora`` files. The Thin - mode lets equivalent properties be set in the application when connecting. - - Configuration files in a "default" location such as the Instant Client - ``network/admin/`` subdirectory, in ``$ORACLE_HOME/network/admin/``, or in - ``$ORACLE_BASE/homes/XYZ/network/admin/`` (in a read-only Oracle Database - home) is not automatically loaded in Thin mode. Default locations are - automatically searched by Thick mode. - -- To use the python-oracledb Thin mode in an ORACLE_HOME database installation - environment, you use an explicit connection string since the ``ORACLE_SID``, - ``TWO_TASK`` and ``LOCAL`` environment variables are not used. They are used - in Thick mode. - -- 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: @@ -445,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 `_. @@ -470,29 +162,29 @@ following steps: 4. Review obsolete encoding parameters in calls to :func:`oracledb.connect()`, ``oracledb.Connection()``, and ``oracledb.SessionPool()``: - - ``encoding`` and ``nencoding`` are ignored by python-oracledb. The - python-oracledb driver uses UTF-8 exclusively. + - ``encoding`` and ``nencoding`` are desupported in python-oracledb and must + be removed. The python-oracledb driver uses UTF-8 exclusively. - - ``threaded`` is ignored in :func:`oracledb.connect()` and - ``oracledb.Connection()`` by python-oracledb. This parameter was already - ignored in ``oracledb.SessionPool()`` from cx_Oracle 8.2. + - ``threaded`` is desupported in :func:`oracledb.connect()` and + ``oracledb.Connection()`` by python-oracledb and must be removed. This + 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.SPOOL_ATTRVAL_WAIT` instead of - :data:`~oracledb.SPOOL_ATTRVAL_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. +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 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_SPOOL_ATTRVAL_NOWAIT``. + explicitly specify ``getmode=oracledb.POOL_GETMODE_NOWAIT``. Note a :ref:`ConnectionPool class ` deprecates the equivalent SessionPool class. The method :meth:`oracledb.create_pool()` deprecates the @@ -500,102 +192,304 @@ following steps: as :data:`~oracledb.POOL_GETMODE_NOWAIT` and :data:`~oracledb.PURITY_SELF` are now preferred. The old namespaces still work. -7. Review the following sections to see if your application requirements are - satisfied by the python-oracledb Thin mode: +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:: - - :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. + python-oracledb Thick mode Error:: -8. Review :ref:`compatibility`. + DPY-1001: not connected to database - If your code base uses an older cx_Oracle version, review the previous - :ref:`release notes ` for additional changes to modernize - the code. + cx_Oracle Error:: -9. Modernize code as needed or desired. See :ref:`deprecations` for the list - of deprecations in python-oracledb 1.0. + not connected + + * Scenario 2: The database side of the connection was terminated while the + connection was being used. + + python-oracledb Thin mode Error:: + + DPY-4011: the database or network closed the connection + + python-oracledb Thick mode Error:: + + DPY-4011: the database or network closed the connection + DPI-1080: connection was closed by ORA-%d + + cx_Oracle Error:: + + DPI-1080: connection was closed by ORA-%d + + * Scenario 3: Statement execution exceeded the :attr:`connection.call_timeout` + value. + + python-oracledb Thin mode Error:: + + DPY-4024: call timeout of {timeout} ms exceeded + + python-oracledb Thick mode Error:: + + DPY-4024: call timeout of {timeout} ms exceeded + DPI-1067: call timeout of %u ms exceeded with ORA-%d + + cx_Oracle Error:: + + DPI-1067: call timeout of %u ms exceeded with ORA-%d + +14. If your code base uses an older cx_Oracle version, review + :ref:`deprecations` for additional changes that may be necessary. + +15. Modernize code to take advantage of new features, if desired. See the + :ref:`release notes `. + +16. Review the following sections to see if your application requirements are + satisfied by python-oracledb Thin mode: + + - :ref:`featuresummary` + - :ref:`driverdiff` + + If so, then follow :ref:`upgradethin`. + + If your application requirements are not supported by python-oracledb Thin + mode, then use Thick mode, see :ref:`upgradethick`. + +.. _upgradethin: Additional Upgrade Steps to use python-oracledb Thin Mode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -To use python-oracledb Thin mode, the following changes need to be made in -addition to the common :ref:`commonupgrade`: +To upgrade from cx_Oracle to python-oracledb Thin mode, the following changes +need to be made in addition to the common :ref:`commonupgrade`: -1. Remove calls to :func:`~oracledb.init_oracle_client` since this turns on the +1. Remove calls to :func:`~oracledb.init_oracle_client` since this turns on 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" - Also see :ref:`sqlnetclientconfig`. + or + + .. code-block:: python -3. If the application is connecting using an :ref:`Oracle Net service name - ` 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 above. + connection = oracledb.connect(user="hr", password=userpwd, dsn="orclpdb", + config_dir="/opt/oracle/config") -4. 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. -5. Ensure that any assumptions about when connections are created in the - connection pool are eliminated. The python-oracledb Thin mode creates + Also, see :ref:`sqlnetclientconfig`. + +3. If the ``driver_name`` parameter of :func:`~oracledb.init_oracle_client` had + been used, then set the new :attr:`defaults.driver_name` attribute to the + desired value or set the ``driver_name`` parameter when connecting. The + convention for this parameter is to separate the product name from the + product version by a colon and single blank characters. For example: + + .. code-block:: python + + oracledb.defaults.driver_name = "python-oracledb : 1.2.0" + + See :ref:`otherinit`. + +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 that - this behavior is also similar in recent versions of the Oracle Call + :attr:`ConnectionPool.opened` will change over time and will not be equal + to :attr:`ConnectionPool.min` immediately after the pool is created. Note + that this behavior is also similar in recent versions of the Oracle Call Interface (OCI) Session Pool used by the Thick mode. Unless the ``oracledb.SessionPool()`` function's parameter ``getmode`` is - ``SPOOL_ATTRVAL_WAIT`` (or the new equivalent - :data:`oracledb.POOL_GETMODE_WAIT`), then applications should not call + :data:`oracledb.POOL_GETMODE_WAIT`, then applications should not call :meth:`ConnectionPool.acquire()` until sufficient time has passed for connections in the pool to be created. -6. 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`. -7. 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 - :ref:`AQ API ` originally introduced in cx_Oracle 7.2, see the - `cx_Oracle Advanced Queuing (AQ) `_ documentation. +- 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 ------------------------------------------ @@ -605,11 +499,11 @@ Code to Aid the Upgrade to python-oracledb 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. +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 obsolete cx_Oracle features or error message +changes. An example application showing this module in use is: @@ -626,9 +520,9 @@ An example application showing this module in use is: connection = cx_Oracle.connect(user=un, password=pw, dsn=cs) with connection.cursor() as cursor: - sql = """SELECT UNIQUE CLIENT_DRIVER - FROM V$SESSION_CONNECT_INFO - WHERE SID = SYS_CONTEXT('USERENV', 'SID')""" + sql = """select unique client_driver + from v$session_connect_info + where sid = sys_context('userenv', 'sid')""" for r, in cursor.execute(sql): print(r) @@ -638,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 @@ -665,30 +559,5 @@ similar to: else: print('oracledb') -Another method that can be used to check which driver is in use is to query -``V$SESSION_CONNECT_INFO``, see :ref:`vsessconinfo`. - -.. _frameworks: - -Python Frameworks, SQL Generators, and ORMs -------------------------------------------- - -The python-oracledb Thin mode features in the python-oracledb cover the needs -of frameworks that depend upon the Python Database API. - -Until SQLAlchemy, Django, other frameworks, object-relational mappers (ORMs), -and libraries add native support for python-oracledb, you can add temporary -code like this to use python-oracledb in-place of cx_Oracle: - -.. code-block:: python - - import sys - import oracledb - oracledb.version = "8.3.0" - sys.modules["cx_Oracle"] = oracledb - import cx_Oracle - -.. note:: - - The import of cx_Oracle occurs last. This code must be run before the - library code does its own import of cx_Oracle. +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`. 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 new file mode 100644 index 00000000..c806c1d1 --- /dev/null +++ b/doc/src/user_guide/asyncio.rst @@ -0,0 +1,667 @@ +.. _asyncio: + +************************************************** +Concurrent Programming with asyncio and Pipelining +************************************************** + +:ref:`concurrentprogramming` and :ref:`Oracle Database Pipelining ` +significantly enhances the overall performance and responsiveness of +applications. + +.. _concurrentprogramming: + +Concurrent Programming with asyncio +=================================== + +The `Asynchronous I/O (asyncio) `__ Python library can be used with python-oracledb Thin mode for +concurrent programming. This library allows you to run operations in parallel, +for example to run a long-running operation in the background without blocking +the rest of the application. With asyncio, you can easily write concurrent code +with the ``async`` and ``await`` syntax. See Python's `Developing with asyncio +`__ documentation for +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 +have corresponding asynchronous counterparts. You can choose whether to use the +synchronous API or the asynchronous API in your code. It is recommended to +*not* use both at the same time in your application. + +The asynchronous API classes are :ref:`AsyncConnection `, +:ref:`AsyncConnectionPool `, +:ref:`AsyncCursor `, and :ref:`AsyncLOB `. + +.. note:: + + Concurrent programming with asyncio is only supported in + python-oracledb Thin mode. + +.. _connasync: + +Connecting to Oracle Database Asynchronously +-------------------------------------------- + +With python-oracledb, you can create an asynchronous connection to Oracle +Database using either :ref:`standalone connections ` or +:ref:`pooled connections `. (For discussion of synchronous +programming, see :ref:`connhandling`.) + +.. _asyncstandalone: + +Standalone Connections +++++++++++++++++++++++ + +Standalone connections are useful for applications that need only a single +connection to a database. + +An asynchronous standalone connection can be created by calling the +asynchronous method :meth:`oracledb.connect_async()` which establishes a +connection to the database and returns an :ref:`AsyncConnection Object +`. Once connections are created, all objects created by these +connections follow the asynchronous programming model. Subject to appropriate +use of ``await`` for calls that require a round-trip to the database, +asynchronous connections are used in the same way that synchronous programs use +:ref:`standaloneconnection`. + +Asynchronous connections should be released when they are no longer needed to +ensure Oracle Database gracefully cleans up. A preferred method is to use an +asynchronous context manager. For example: + +.. code-block:: python + + import asyncio + import oracledb + + async def main(): + + async with oracledb.connect_async(user="hr", password=userpwd, + dsn="localhost/orclpdb") as connection: + with connection.cursor() as cursor: + await cursor.execute("select user from dual") + async for result in cursor: + print(result) + + asyncio.run(main()) + +This code ensures that once the block is completed, the connection is closed +and resources are reclaimed by the database. In addition, any attempt to use +the variable ``connection`` outside of the block will fail. + +If you do not use a context manager, you should explicitly close connections +when they are no longer needed, for example: + +.. code-block:: python + + connection = await oracle.connect_async(user="hr", password=userpwd, + dsn="localhost/orclpdb") + + cursor = connection.cursor() + + await cursor.execute("select user from dual") + async for result in cursor: + print(result) + + cursor.close() + await connection.close() + + +.. _asyncconnpool: + +Connection Pools +++++++++++++++++ + +Connection pooling allows applications to create and maintain a pool of open +connections to the database. Connection pooling is important for performance +and scalability when applications need to handle a large number of users who do +database work for short periods of time but have relatively long periods when +the connections are not needed. The high availability features of pools also +make small pools useful for applications that want a few connections available +for infrequent use and requires them to be immediately usable when acquired. + +An asynchronous connection pool can be created by calling +:meth:`oracledb.create_pool_async()` which returns an :ref:`AsyncConnectionPool +Object `. Note that this method is *synchronous* and does not +use ``await``. Once the pool has been created, your application can get a +connection from it by calling :meth:`AsyncConnectionPool.acquire()`. After +your application has used a connection, it should be released back to the pool +to make it available for other users. This can be done by explicitly closing +the connection or by using an asynchronous context manager, for example: + +.. code-block:: python + + import asyncio + import oracledb + + async def main(): + + pool = oracle.create_pool_async(user="hr", password=userpwd, + dsn="localhost/orclpdb", + min=1, max=4, increment=1) + + async with pool.acquire() as connection: + with connection.cursor() as cursor: + await cursor.execute("select user from dual") + async for result in cursor: + print(result) + + await pool.close() + + asyncio.run(main()) + + +.. _sqlexecuteasync: + +Executing SQL Using Asynchronous Methods +---------------------------------------- + +This section covers executing SQL using the asynchronous programming model. +For discussion of synchronous programming, see :ref:`sqlexecution`. + +Your application communicates with Oracle Database by executing SQL +statements. Statements such as queries (statements beginning with SELECT or +WITH), Data Manipulation Language (DML), and Data Definition Language (DDL) are +executed using the asynchronous methods :meth:`AsyncCursor.execute()` or +:meth:`AsyncCursor.executemany()`. Rows can be iterated over, or fetched using +one of the methods :meth:`AsyncCursor.fetchone()`, +:meth:`AsyncCursor.fetchone()`, :meth:`AsyncCursor.fetchmany()`, or +:meth:`AsyncCursor.fetchall()`. + +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()`, :meth:`AsyncConnection.fetchall()`, +:meth:`AsyncConnection.fetch_df_all()`, or +:meth:`AsyncConnection.fetch_df_batches()`. + +An example of using :meth:`AsyncConnection.fetchall()`: + +.. code-block:: python + + import asyncio + import oracledb + + async def main(): + + async with oracledb.connect_async(user="hr", password=userpwd, + dsn="localhost/orclpdb") as connection: + res = await connection.fetchall("select * from locations") + print(res) + + asyncio.run(main()) + +An example that uses asyncio for parallelization and shows the execution of +multiple coroutines: + +.. code-block:: python + + import asyncio + import oracledb + + # Number of coroutines to run + CONCURRENCY = 5 + + # Query the unique session identifier/serial number combination of a connection + SQL = """SELECT UNIQUE CURRENT_TIMESTAMP AS CT, sid||'-'||serial# AS SIDSER + FROM V$SESSION_CONNECT_INFO + WHERE sid = SYS_CONTEXT('USERENV', 'SID')""" + + # Show the unique session identifier/serial number of each connection that the + # pool opens + async def init_session(connection, requested_tag): + res = await connection.fetchone(SQL) + print(res[0].strftime("%H:%M:%S.%f"), '- init_session with SID-SERIAL#', res[1]) + + # The coroutine simply shows the session identifier/serial number of the + # connection returned by the pool.acquire() call + async def query(pool): + async with pool.acquire() as connection: + await connection.callproc("dbms_session.sleep", [1]) + res = await connection.fetchone(SQL) + print(res[0].strftime("%H:%M:%S.%f"), '- query with SID-SERIAL#', res[1]) + + async def main(): + + pool = oracledb.create_pool_async(user="hr", password=userpwd, + dsn="localhost/orclpdb", + min=1, max=CONCURRENCY, + session_callback=init_session) + + coroutines = [ query(pool) for i in range(CONCURRENCY) ] + + await asyncio.gather(*coroutines) + + await pool.close() + + asyncio.run(main()) + +When you run this, you will see that multiple connections (identified by the +unique Session Identifier and Serial Number combination) are opened and are +used by ``query()``. For example:: + + 12:09:29.711525 - init_session with SID-SERIAL# 36-38096 + 12:09:29.909769 - init_session with SID-SERIAL# 33-56225 + 12:09:30.085537 - init_session with SID-SERIAL# 14-31431 + 12:09:30.257232 - init_session with SID-SERIAL# 285-40270 + 12:09:30.434538 - init_session with SID-SERIAL# 282-32608 + 12:09:30.730166 - query with SID-SERIAL# 36-38096 + 12:09:30.933957 - query with SID-SERIAL# 33-56225 + 12:09:31.115008 - query with SID-SERIAL# 14-31431 + 12:09:31.283593 - query with SID-SERIAL# 285-40270 + 12:09:31.457474 - query with SID-SERIAL# 282-32608 + +Your results may vary depending how fast your environment is. + +See `async_gather.py `__ for a runnable example. + +.. _txnasync: + +Managing Transactions Using Asynchronous Methods +------------------------------------------------ + +This section covers managing transactions using the asynchronous programming +model. For discussion of synchronous programming, see :ref:`txnmgmnt`. + +When :meth:`AsyncCursor.execute()` or :meth:`AsyncCursor.executemany()` +executes a SQL statement, a transaction is started or continued. By default, +python-oracledb does not commit this transaction to the database. The methods +:meth:`AsyncConnection.commit()` and :meth:`AsyncConnection.rollback()` +methods can be used to explicitly commit or rollback a transaction: + +.. code-block:: python + + async def main(): + async with oracledb.connect_async(user="hr", password=userpwd, + dsn="localhost/orclpdb") as connection: + + with connection.cursor as cursor: + await cursor.execute("INSERT INTO mytab (name) VALUES ('John')") + await connection.commit() + +When a database connection is closed, such as with +:meth:`AsyncConnection.close()`, or when variables referencing the connection +go out of scope, any uncommitted transaction will be rolled back. + +An alternative way to commit is to set the attribute +:attr:`AsyncConnection.autocommit` of the connection to ``True``. This +ensures all :ref:`DML ` statements (INSERT, UPDATE, and so on) are +committed as they are executed. + +Note that irrespective of the autocommit value, Oracle Database will always +commit an open transaction when a DDL statement is executed. + +When executing multiple DML statements that constitute a single transaction, it +is recommended to use autocommit mode only for the last DML statement in the +sequence of operations. Unnecessarily committing causes extra database load, +and can destroy transactional consistency. + +.. _pipelining: + +Pipelining Database Operations +============================== + +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 +the database processes the pipeline of statements, the application can continue +with non-database work. When the database has executed all the pipelined +operations, their results are returned to the application. + +Pipelined operations are executed sequentially by the database. They do not +execute concurrently. It is local tasks that can be executed at the same time +the database is working. + +Effective use of Oracle Database Pipelining can increase the responsiveness of +an application and improve overall system throughput. Pipelining is useful when +many small operations are being performed in rapid succession. It is most +beneficial when the network to the database is slow. This is because of its +reduction in :ref:`round-trips ` compared with those required if +the equivalent SQL statements were individually executed with calls like +:meth:`AsyncCursor.execute()`. + +Pipelining is only supported in python-oracledb Thin mode with +:ref:`asyncio `. + +See `Oracle Call Interface Pipelining +`__ for more information +about Oracle Database Pipelining. + +.. note:: + + True pipelining only occurs when you are connected to Oracle Database 23ai. + + When you connect to an older database, operations are sequentially + executed by python-oracledb. Each operation concludes before the next is + sent to the database. There is no reduction in round-trips and no + performance benefit. This usage is only recommended for code portability + such as when preparing for a database upgrade. + +Using Pipelines +--------------- + +To create a :ref:`pipeline ` to process a set of database +operations, use :meth:`oracledb.create_pipeline()`. + +.. code-block:: python + + pipeline = oracledb.create_pipeline() + +You can then add various operations to the pipeline using +:meth:`~Pipeline.add_callfunc()`, :meth:`~Pipeline.add_callproc()`, +:meth:`~Pipeline.add_commit()`, :meth:`~Pipeline.add_execute()`, +:meth:`~Pipeline.add_executemany()`, :meth:`~Pipeline.add_fetchall()`, +:meth:`~Pipeline.add_fetchmany()`, and :meth:`~Pipeline.add_fetchone()`. For +example: + +.. code-block:: python + + pipeline.add_execute("insert into mytable (mycol) values (1234)") + pipeline.add_fetchone("select user from dual") + pipeline.add_fetchmany("select employee_id from employees", num_rows=20) + +Note that queries that return results do not call ``add_execute()``. + +Only one set of query results can be returned from each query operation. For +example :meth:`~Pipeline.add_fetchmany()` will only fetch the first set of +query records, up to the limit specified by the method's ``num_rows`` +parameter. Similarly for :meth:`~Pipeline.add_fetchone()` only the first row +can ever be fetched. It is not possible to fetch more data from these +operations. To prevent the database processing rows that cannot be fetched by +the application, consider adding appropriate ``WHERE`` conditions or using a +``FETCH NEXT`` clause in the statement, see :ref:`rowlimit`. + +Query results or :ref:`OUT binds ` from one operation cannot be passed to +subsequent operations in the same pipeline. + +To execute the pipeline, call :meth:`AsyncConnection.run_pipeline()`. + +.. code-block:: python + + results = await connection.run_pipeline(pipeline) + +The operations are all sent to the database and executed. The method returns a +list of :ref:`PipelineOpResult objects `, one entry per +operation. The objects contain information about the execution of the relevant +operation, such as any error number, PL/SQL function return value, or any query +rows and column metadata. + + +The :attr:`Connection.call_timeout` value has no effect on pipeline operations. +To limit the time for a pipeline, use an `asyncio timeout +`__, available +from Python 3.11. + +To tune fetching of rows with :meth:`Pipeline.add_fetchall()`, set +:attr:`defaults.arraysize` or pass the ``arraysize`` parameter. + +Pipelining Examples ++++++++++++++++++++ + +An example of pipelining is: + +.. code-block:: python + + import asyncio + import oracledb + + async def main(): + # Create a pipeline and define the operations + pipeline = oracledb.create_pipeline() + pipeline.add_fetchone("select temperature from weather") + pipeline.add_fetchall("select name from friends where active = true") + pipeline.add_fetchmany("select story from news order by popularity", num_rows=5) + + connection = await oracle.connect_async(user="hr", password=userpwd, + dsn="localhost/orclpdb") + + # Run the operations in the pipeline + result_1, result_2, result_3 = await connection.run_pipeline(pipeline) + + # Print the database responses + print("Current temperature:", result_1.rows) + print("Active friends:", result_2.rows) + print("Top news stories:", result_3.rows) + + await connection.close() + + asyncio.run(main()) + +See `pipelining_basic.py +`__ +for a runnable example. + +To allow an application to continue with non-database work before processing +any responses from the database, use code similar to: + +.. code-block:: python + + async def run_thing_one(): + return "thing_one" + + async def run_thing_two(): + return "thing_two" + + async def main(): + connection = await oracle.connect_async(user="hr", password=userpwd, + dsn="localhost/orclpdb") + + pipeline = oracledb.create_pipeline() + pipeline.add_fetchone("select user from dual") + pipeline.add_fetchone("select sysdate from dual") + + # Run the pipeline and non-database operations concurrently + return_values = await asyncio.gather( + run_thing_one(), run_thing_two(), connection.run_pipeline(pipeline) + ) + + for r in return_values: + if isinstance(r, list): # the pipeline return list + for result in r: + if result.rows: + for row in result.rows: + print(*row, sep="\t") + else: + print(r) # a local operation result + + await connection.close() + + asyncio.run(main()) + +Output will be like:: + + thing_one + thing_two + HR + 2024-10-29 03:34:43 + +See `pipelining_parallel.py +`__ +for a runnable example. + +Using OUT Binds with Pipelines +------------------------------ + +To fetch :ref:`OUT binds ` from executed statements, create an explicit +cursor and use :meth:`Cursor.var()`. These variables are associated with the +connection and can be used by the other cursors created internally for each +pipelined operation. For example: + +.. code-block:: python + + cursor = connection.cursor() + v1 = cursor.var(oracledb.DB_TYPE_BOOLEAN) + v2 = cursor.var(oracledb.DB_TYPE_VARCHAR) + + pipeline = oracledb.create_pipeline() + + pipeline.add_execute(""" + begin + :1 := true; + :2 := 'Python'; + end; + """, [v1, v2]) + pipeline.add_fetchone("select 1234 from dual") + + results = await connection.run_pipeline(pipeline) + + for r in results: + if r.rows: + print(r.rows) + + print(v1.getvalue(), v2.getvalue()) + +This prints:: + + [(1234,)] + True Python + +OUT binds from one operation cannot be used in subsequent operations. For +example the following would print only ``True`` because the WHERE condition of +the SQL statement is not matched: + +.. code-block:: python + + cursor = connection.cursor() + v1 = cursor.var(oracledb.DB_TYPE_BOOLEAN) + + pipeline = oracledb.create_pipeline() + + pipeline.add_execute(""" + begin + :1 := TRUE; + end; + """, [v1]) + pipeline.add_fetchone("select 1234 from dual where :1 = TRUE", [v1]) + + results = await connection.run_pipeline(pipeline) + + for r in results: + if r.rows: + print(r.rows) + + print(v1.getvalue()) # prints True + +Pipeline Error Handling +----------------------- + +The ``continue_on_error`` parameter to :meth:`AsyncConnection.run_pipeline()` +determines whether subsequent operations should continue to run after a failure +in one operation has occurred. When set to the default value False, if any +error is returned in any operation in the pipeline then the database terminates +all subsequent operations. + +For example: + +.. code-block:: python + + # Stop on error + + pipeline.add_fetchall("select 1234 from does_not_exist") + pipeline.add_fetchone("select 5678 from dual") + + r1, r2 = await connection.run_pipeline(pipeline) + +will only execute the first operation and will throw the failure message:: + + oracledb.exceptions.DatabaseError: ORA-00942: table or view "HR"."DOES_NOT_EXIST" does not exist + Help: https://docs.oracle.com/error-help/db/ora-00942/ + + +whereas this code: + +.. code-block:: python + + # Continue on error + + pipeline.add_fetchall("select 1234 from does_not_exist") + pipeline.add_fetchone("select 5678 from dual") + + r1, r2 = await connection.run_pipeline(pipeline, continue_on_error=True) + + print(r1.error) + print(r2.rows) + +will execute all operations and will display:: + + ORA-00942: table or view "HR"."DOES_NOT_EXIST" does not exist + Help: https://docs.oracle.com/error-help/db/ora-00942/ + [(5678,)] + +.. _pipelinewarning: + +**PL/SQL Compilation Warnings** + +:ref:`plsqlwarning` can be identified by checking the :ref:`PipelineOpResult +Attribute ` :attr:`PipelineOpResult.warning`. For +example: + +.. code-block:: python + + pipeline.add_execute( + """create or replace procedure myproc as + begin + bogus; + end;""" + ) + (result,) = await connection.run_pipeline(pipeline) + + print(result.warning.full_code) + print(result.warning) + +will print:: + + DPY-7000 + DPY-7000: creation succeeded with compilation errors + + +See `pipelining_error.py +`__ +for a runnable example showing warnings and errors. + + +Pipeline Cursor Usage +--------------------- + +For each operation added to a pipeline, with the exception of +:meth:`Pipeline.add_commit()`, a cursor will be opened when +:meth:`AsyncConnection.run_pipeline()` is called. For example, the following +code will open two cursors: + +.. code-block:: python + + pipeline = oracledb.create_pipeline() + pipeline.add_execute("insert into t1 (c1) values (1234)") + pipeline.add_fetchone("select user from dual") + + await connection.run_pipeline(pipeline) + +Make sure your pipeline length does not exceed your cursor limit. Set the +database parameter `open_cursors +`__ +appropriately. + +Pipeline Round-trips +-------------------- + +The complete set of operations in a pipeline will be performed in a single +:ref:`round-trip ` when :meth:`AsyncConnection.run_pipeline()` is +called, with the following exceptions: + +- Queries that contain :ref:`LOBs ` require an additional + round-trip +- Queries that contain :ref:`DbObject ` values may require multiple + round-trips +- Queries with :meth:`~Pipeline.add_fetchall()` may require multiple + round-trips + +The reduction in round-trips is the significant contributor to pipelining's +performance improvement in comparison to explicitly executing the equivalent +SQL statements individually. With high-speed networks there may be little +performance benefit to using pipelining, however the database and network +efficiencies can help overall system scalability. + +Note that the traditional method of monitoring round-trips by taking snapshots +of the V$SESSTAT view is not accurate for pipelines. diff --git a/doc/src/user_guide/batch_statement.rst b/doc/src/user_guide/batch_statement.rst index ad4969a2..17a2831a 100644 --- a/doc/src/user_guide/batch_statement.rst +++ b/doc/src/user_guide/batch_statement.rst @@ -1,10 +1,13 @@ .. _batchstmnt: -******************************************* -Executing Batch Statements and Bulk Loading -******************************************* +**************************************** +Batch Statement and Bulk Copy Operations +**************************************** -Inserting or updating multiple rows can be performed efficiently with +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 python-oracledb. This method can significantly outperform repeated calls to :meth:`Cursor.execute()` by reducing network transfer costs and database @@ -36,21 +39,23 @@ 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``: .. code-block:: python data = [ - (10, 'Parent 10'), - (20, 'Parent 20'), - (30, 'Parent 30'), - (40, 'Parent 40'), - (50, 'Parent 50') + (10, "Parent 10"), + (20, "Parent 20"), + (30, "Parent 30"), + (40, "Parent 40"), + (50, "Parent 50") ] cursor.executemany("insert into ParentTable values (:1, :2)", data) +Each tuple value maps to one of the bind variable placeholders. + This code requires only one :ref:`round-trip ` from the client to the database instead of the five round-trips that would be required for repeated calls to :meth:`~Cursor.execute()`. For very large data sets, there @@ -60,6 +65,32 @@ on both the number of rows being processed as well as the "size" of each row that is being processed. Repeated calls to :meth:`~Cursor.executemany()` are still better than repeated calls to :meth:`~Cursor.execute()`. +To insert a single column, make sure the bind variables are correctly created +as tuples, for example: + +.. code-block:: python + + data = [ + (10,), + (20,), + (30,), + ] + cursor.executemany('insert into mytable (mycol) values (:1)', data) + +Named binds can be performed by passing an array of dicts, where the keys match +the bind variable placeholder names: + +.. code-block:: python + + data = [ + {"pid": 10, "pdesc": "Parent 10"}, + {"pid": 20, "pdesc": "Parent 20"}, + {"pid": 30, "pdesc": "Parent 30"}, + {"pid": 40, "pdesc": "Parent 40"}, + {"pid": 50, "pdesc": "Parent 50"} + ] + cursor.executemany("insert into ParentTable values :pid, :pdesc)", data) + Predefining Memory Areas ------------------------ @@ -102,33 +133,162 @@ since numeric data is already stored efficiently. Since python-oracledb allocates memory for each row based on the supplied values, do not oversize them. +If the size of the buffers allocated for any of the bind values exceeds 2 GB, +you will receive the error ``DPI-1015: array size of is too large``, where + varies with the size of each element being allocated in the buffer. If you +receive this error, decrease the number of rows being inserted. + +With named bind variables, use named parameters when calling +:meth:`~Cursor.setinputsizes()`: + +.. code-block:: python + + data = [ + {"pid": 110, "pdesc": "Parent 110"}, + {"pid": 2000, "pdesc": "Parent 2000"}, + {"pid": 30000, "pdesc": "Parent 30000"}, + {"pid": 400000, "pdesc": "Parent 400000"}, + {"pid": 5000000, "pdesc": "Parent 5000000"} + ] + cursor.setinputsizes(pdesc=20) + cursor.executemany(""" + insert into ParentTable (ParentId, Description) + values (:pid, :pdesc)""", data) + + +.. _batchplsql: + Batch Execution of PL/SQL -========================= +------------------------- -PL/SQL functions and procedures and anonymous PL/SQL blocks can also be called -using :meth:`~Cursor.executemany()` in order to improve performance. For -example: +Using :meth:`~Cursor.executemany()` can improve performance when PL/SQL +functions, procedures, or anonymous blocks need to be called multiple times. + +Runnable examples are in `plsql_batch.py `__. + +**IN Binds** + +An example using :ref:`bind by position ` for IN binds is: .. code-block:: python data = [ - (10, 'Parent 10'), - (20, 'Parent 20'), - (30, 'Parent 30'), - (40, 'Parent 40'), - (50, 'Parent 50') + (10, "Parent 10"), + (20, "Parent 20"), + (30, "Parent 30"), + (40, "Parent 40"), + (50, "Parent 50") ] cursor.executemany("begin mypkg.create_parent(:1, :2); end;", data) -If ``executemany()`` is used for PL/SQL code that returns OUT binds it will -have the same performance characteristics as repeated calls to ``execute()``. +Note that the ``batcherrors`` parameter of :meth:`~Cursor.executemany()` +(discussed in :ref:`batcherrors`) cannot be used with PL/SQL block execution. + +**OUT Binds** + +When using OUT binds in PL/SQL, the input data omits entries for the OUT bind +variable placeholders. An example PL/SQL procedure that returns OUT binds is: + +.. code-block:: sql + + create or replace procedure myproc(p1 in number, p2 out number) as + begin + p2 := p1 * 2; + end; + +This can be called in python-oracledb using positional binds like: + +.. code-block:: python + + data = [ + (100,), + (200,), + (300,) + ] + + outvals = cursor.var(oracledb.DB_TYPE_NUMBER, arraysize=len(data)) + cursor.setinputsizes(None, outvals) + + cursor.executemany("begin myproc(:1, :2); end;", data) + print(outvals.values) + +The output is:: + + [200, 400, 600] + +The equivalent code using named binds is: + +.. code-block:: python + + data = [ + {"p1bv": 100}, + {"p1bv": 200}, + {"p1bv": 300} + ] + + outvals = cursor.var(oracledb.DB_TYPE_NUMBER, arraysize=len(data)) + cursor.setinputsizes(p1bv=None, p2bv=outvals) -Note that the ``batcherrors`` parameter (discussed below) cannot be used with -PL/SQL block execution. + cursor.executemany("begin myproc(:p1bv, :p2bv); end;", data) + print(outvals.values) +Note that in python-oracledb Thick mode, when :meth:`~Cursor.executemany()` is +used for PL/SQL code that returns OUT binds, it will have the same performance +characteristics as repeated calls to :meth:`~Cursor.execute()`. + +**IN/OUT Binds** + +An example PL/SQL procedure that returns IN/OUT binds is: + +.. code-block:: sql + + create or replace procedure myproc2 (p1 in number, p2 in out varchar2) as + begin + p2 := p2 || ' ' || p1; + end; + +This can be called in python-oracledb using positional binds like: + +.. code-block:: python + + data = [ + (440, 'Gregory'), + (550, 'Haley'), + (660, 'Ian') + ] + outvals = cursor.var(oracledb.DB_TYPE_VARCHAR, size=100, arraysize=len(data)) + cursor.setinputsizes(None, outvals) + + cursor.executemany("begin myproc2(:1, :2); end;", data) + print(outvals.values) + +The ``size`` parameter of :meth:`Cursor.var()` indicates the maximum length of +the string that can be returned. + +Output is:: + + ['Gregory 440', 'Haley 550', 'Ian 660'] + +The equivalent code using named binds is: + +.. code-block:: python + + data = [ + {"p1bv": 440, "p2bv": 'Gregory'}, + {"p1bv": 550, "p2bv": 'Haley'}, + {"p1bv": 660, "p2bv": 'Ian'} + ] + outvals = cursor.var(oracledb.DB_TYPE_VARCHAR, size=100, arraysize=len(data)) + cursor.setinputsizes(p1bv=None, p2bv=outvals) + + cursor.executemany("begin myproc2(:p1bv, :p2bv); end;", data) + print(outvals.values) + +.. _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 @@ -149,12 +309,12 @@ This example shows how data errors can be identified: .. code-block:: python data = [ - (60, 'Parent 60'), - (70, 'Parent 70'), - (70, 'Parent 70 (duplicate)'), - (80, 'Parent 80'), - (80, 'Parent 80 (duplicate)'), - (90, 'Parent 90') + (60, "Parent 60"), + (70, "Parent 70"), + (70, "Parent 70 (duplicate)"), + (80, "Parent 80"), + (80, "Parent 80 (duplicate)"), + (90, "Parent 90") ] cursor.executemany("insert into ParentTable values (:1, :2)", data, batcherrors=True) @@ -174,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 @@ -204,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. @@ -239,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 @@ -303,3 +473,77 @@ prevent all data being inserted at once: 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 `samples/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. + + +Bulk Copying Data between Databases +----------------------------------- + +The :meth:`Cursor.executemany()` function is useful for copying data from one +database to another: + +.. code-block:: python + + # Connect to both databases + source_connection = oracledb.connect(user=un1, password=pw1, dsn=cs1) + target_connection = oracledb.connect(user=un2, password=pw2, dsn=cs2) + + # Setup cursors + source_cursor = source_connection.cursor() + source_cursor.arraysize = 1000 # tune this for query performance + + target_cursor = target_connection.cursor() + target_cursor.setinputsizes(None, 25) # set according to column types + + # Perform bulk fetch and insertion + source_cursor.execute("select c1, c2 from MySrcTable") + while True: + rows = source_cursor.fetchmany() + if not rows: + break + target_cursor.executemany("insert into MyDestTable values (:1, :2)", rows) + + target_connection.commit() + +Tune the :attr:`~Cursor.arraysize` value according to notes in +:ref:`tuningfetch`. Use ``setinputsizes()`` according to `Predefining Memory +Areas`_. + +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 7b9468b4..fe5394d6 100644 --- a/doc/src/user_guide/bind.rst +++ b/doc/src/user_guide/bind.rst @@ -6,71 +6,127 @@ Using Bind Variables SQL and PL/SQL statements that pass data to and from Oracle Database should use placeholders in SQL and PL/SQL statements that mark where data is supplied or -returned. These placeholders are referred to as bind variables or bind -parameters. A bind variable is a colon-prefixed identifier or numeral. For -example, there are two bind variables (``dept_id`` and ``dept_name``) in this -SQL statement: +returned. A bind variable placeholder is a colon-prefixed identifier or +numeral. For example, ``:dept_id`` and ``:dept_name`` are the two bind variable +placeholders in this SQL statement: .. code-block:: python sql = """insert into departments (department_id, department_name) - values (:dept_id, :dept_name)""" + values (:dept_id, :dept_name)""" cursor.execute(sql, [280, "Facility"]) +As part of execution, the supplied bind variable values ``280`` and +``"Facility"`` are substituted for the placeholders by the database. This is +called binding. + Using bind variables is important for scalability and security. They help avoid SQL Injection security problems because data is never treated as part of an -executable statement. Never concatenate or interpolate user data into SQL -statements: - -.. code-block:: python - - did = 280 - dnm = "Facility" - - # !! Never do this !! - sql = f"""insert into departments (department_id, department_name) - values ({did}, '{dnm}')""" - cursor.execute(sql) +executable statement when it is parsed. Bind variables reduce parsing and execution costs when statements are executed 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. +.. warning:: + + Never concatenate or interpolate user data into SQL statements: + + .. code-block:: python + + did = 280 + dnm = "Facility" + + # !! Never do this !! + sql = f"""insert into departments (department_id, department_name) + values ({did}, '{dnm}')""" + cursor.execute(sql) + + This is a security risk and can impact performance and scalability. + Bind variables can be used to substitute data, but cannot be used to substitute -the text of the statement. You cannot, for example, use a bind variable where -a column name or a table name is required. Bind variables also cannot be used -in Data Definition Language (DDL) statements, such as CREATE TABLE or ALTER -statements. +the text of the statement. You cannot, for example, use a bind variable +placeholder where a column name or a table name is required. Bind variable +placeholders also cannot be used in Data Definition Language (DDL) statements, +such as CREATE TABLE or ALTER statements. Binding by Name or Position =========================== -Binding can be done by name or by position. A named bind is performed when the -bind variables in a statement are associated with a name. For example: +Binding can be done "by name" or "by position". + +.. _bindbyname: + +Bind by Name +------------ + +A named bind is performed when the bind variables in the Python statement use +the names of placeholders in the SQL or PL/SQL statement. For example: .. code-block:: python cursor.execute(""" insert into departments (department_id, department_name) - values (:dept_id, :dept_name)""", dept_id=280, - dept_name="Facility") + values (:dept_id, :dept_name)""", + dept_id=280, dept_name="Facility") + +Alternatively, the parameters can be passed as a dictionary instead of as +keyword parameters: + +.. code-block:: python - # alternatively, the parameters can be passed as a dictionary instead of as - # keyword parameters data = dict(dept_id=280, dept_name="Facility") cursor.execute(""" insert into departments (department_id, department_name) values (:dept_id, :dept_name)""", data) -In the above example, the keyword parameter names or the keys of the dictionary -must match the bind variable names. The advantages of this approach are that -the location of the bind variables in the statement is not important, the -names can be meaningful and the names can be repeated while still only -supplying the value once. +In the above examples, the keyword parameter names or the keys of the +dictionary must match the bind variable placeholder names. + +The advantages of named binding are that the order of the bind values in the +``execute()`` parameter is not important, the names can be meaningful, and the +placeholder names can be repeated while still only supplying the value once in +the application. + +An example of reusing a bind variable placeholder is: + +.. code-block:: python + + cursor.execute(""" + update departments set department_id = :dept_id + 10 + where department_id = :dept_id""", + dept_id=280) + +.. _bindbyposition: + +Bind by Position +---------------- + +Positional binding occurs when a list or tuple of bind values is passed to the +``execute()`` call. For example: + +.. code-block:: python + + cursor.execute(""" + insert into departments (department_id, department_name) + values (:1, :2)""", [280, "Facility"]) + +The following example (which changes the order of the bind placeholder names) +has exactly the same behavior. The value used to substitute the placeholder +":2" will be the first element of the list and ":1" will be replaced by the +second element. Bind by position works from left to right and pays no +attention to the name of the bind variable: + +.. code-block:: python + + cursor.execute(""" + insert into departments (department_id, department_name) + values (:2, :1)""", [280, "Facility"]) -A positional bind is performed when a list of bind values are passed to the -execute() call. For example: +The following example is also bind by position despite the bind placeholders +having alphabetic names. The actual process of binding uses the list positions +of the input data to associate the data with the placeholder locations: .. code-block:: python @@ -78,21 +134,34 @@ execute() call. For example: insert into departments (department_id, department_name) values (:dept_id, :dept_name)""", [280, "Facility"]) -Note that for SQL statements, the order of the bind values must exactly match -the order of each bind variable and duplicated names must have their values -repeated. For PL/SQL statements, however, the order of the bind values must -exactly match the order of each **unique** bind variable found in the PL/SQL -block and values should not be repeated. In order to avoid this difference, -binding by name is recommended when bind variable names are repeated. + +Python tuples can also be used for binding by position: + +.. code-block:: python + + cursor.execute(""" + insert into departments (department_id, department_name) + values (:1, :2)""", (280, "Facility")) + +If only a single bind placeholder is used in the SQL or PL/SQL statement, the +data can be a list like ``[280]`` or a single element tuple like ``(280,)``. + +When using bind by position for SQL statements, the order of the bind values +must exactly match the order of each bind variable and duplicated names must +have their values repeated. For PL/SQL statements, however, the order of the +bind values must exactly match the order of each **unique** bind variable found +in the PL/SQL block and values should not be repeated. In order to avoid this +difference, binding by name is recommended when bind variable names are +repeated. Bind Direction ============== -The caller can supply data to the database (IN), the database can return -data to the caller (OUT) or the caller can supply initial data to the -database and the database can supply the modified data back to the caller -(IN/OUT). This is known as the bind direction. +The caller can supply data to the database (IN), the database can return data +to the caller (OUT) or the caller can supply initial data to the database and +the database can supply the modified data back to the caller (IN/OUT). This is +known as the bind direction. The examples shown above have all supplied data to the database and are therefore classified as IN bind variables. In order to have the database return @@ -138,32 +207,52 @@ have a value set will start out with a value of ``null``. Binding Null Values =================== -In python-oracledb, null values are represented by the Python singleton ``None``. +To insert a NULL into a character column you can bind the Python singleton +``None``. For example, with the table:: -For example: + create table tab (id number, val varchar2(50)); + +You can use: .. code-block:: python - cursor.execute(""" - insert into departments (department_id, department_name) - values (:dept_id, :dept_name)""", dept_id=280, dept_name=None) + cursor.execute("insert into tab (id, val) values (:i, :v)", i=280, v=None) + +Python-oracledb assumes the value will be a string (equivalent to a VARCHAR2 +column). If you need to use a different Oracle Database data type you will need +to make a call to :func:`Cursor.setinputsizes()` or create a bind variable with +the correct type by calling :func:`Cursor.var()`. + +For example, if the table had been created using an :ref:`Oracle Spatial +SDO_GEOMETRY ` object column:: + + create table tab (id number, val sdo_geometry); -In this specific case, since the ``DEPARTMENT_NAME`` column is defined as a -``NOT NULL`` column, an error will occur:: +Then the previous code would fail with:: - oracledb.IntegrityError: ORA-01400: cannot insert NULL into ("HR"."DEPARTMENTS"."DEPARTMENT_NAME") + ORA-00932: expression is of data type CHAR, which is incompatible with expected data type MDSYS.SDO_GEOMETRY +To insert a NULL into the new table, use: -If this value is bound directly, python-oracledb assumes it to be a string -(equivalent to a VARCHAR2 column). If you need to use a different Oracle type -you will need to make a call to :func:`Cursor.setinputsizes()` or create a bind -variable with the correct type by calling :func:`Cursor.var()`. +.. code-block:: python + + type_obj = connection.gettype("SDO_GEOMETRY") + var = cursor.var(type_obj) + cursor.execute("insert into tab (id, val) values (:i, :v)", i=280, v=var) + +Alternatively use: + +.. code-block:: python + + type_obj = connection.gettype("SDO_GEOMETRY") + cursor.setinputsizes(i=None, v=type_obj) + cursor.execute("insert into tab (id, val) values (:i, :v)", i=280, v=None) Binding ROWID Values ==================== -The pseudo-column ``ROWID`` uniquely identifies a row in a table. In +The pseudo-column ROWID uniquely identifies a row in a table. In python-oracledb, ROWID values are represented as strings. The example below shows fetching a row and then updating that row by binding its rowid: @@ -225,6 +314,8 @@ UROWID can be bound with type :attr:`oracledb.DB_TYPE_ROWID`. See :ref:`querymetadatadiff`. +.. _dml-returning-bind: + DML RETURNING Bind Variables ============================ @@ -249,9 +340,28 @@ In the above example, since the WHERE clause matches only one row, the output contains a single item in the list. If the WHERE clause matched multiple rows, the output would contain as many items as there were rows that were updated. -No duplicate binds are allowed in a DML statement with a RETURNING clause, and -no duplication is allowed between bind variables in the DML section and the -RETURNING section of the statement. +The same bind variable placeholder name cannot be used both before and after +the RETURNING clause. For example, if the ``:dept_name`` bind variable is used +both before and after the RETURNING clause: + +.. code-block:: python + + # a variable cannot be used for both input and output in a DML returning + # statement + dept_name_var = cursor.var(str) + dept_name_var.setvalue(0, 'Input Department') + cursor.execute(""" + update departments set + department_name = :dept_name || ' EXTRA TEXT' + returning department_name into :dept_name""", + dept_name=dept_name_var) + +The above example will not update the bind variable as expected, but no error +will be raised if you are using python-oracledb Thick mode. With +python-oracledb Thin mode, the above example returns the following error:: + + DPY-2048: the bind variable placeholder ":dept_name" cannot be used + both before and after the RETURNING clause in a DML RETURNING statement LOB Bind Variables @@ -325,6 +435,9 @@ return type of :meth:`Cursor.callfunc()`: See :ref:`tuning` for information on how to tune REF CURSORS. +Also see :ref:`Implicit Results ` which provides an +alternative way to return query results from PL/SQL procedures. + Binding PL/SQL Collections ========================== @@ -446,7 +559,7 @@ This would produce the following output:: Demo out element #4 Demo out element #5 -The Python code to process an IN/OUT collections is similar. Note the different +The Python code to process IN/OUT collections is similar. Note the different call to :meth:`Cursor.arrayvar()` which creates space for an array of strings, but uses an array to determine both the maximum length of the array and its initial value. @@ -526,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'} @@ -666,6 +779,97 @@ committed to database. This is similar to the examples above. An example of fetching SDO_GEOMETRY is in :ref:`Oracle Database Objects and Collections `. +.. _sqlversioncount: + +Reducing the SQL Version Count +============================== + +When repeated calls to :meth:`Cursor.execute()` or :meth:`Cursor.executemany()` +bind different string data lengths, then using :meth:`Cursor.setinputsizes()` +can help reduce Oracle Database's SQL "`version count +`__" for the +statement. The version count is the number of child cursors used for the same +statement text. The database will have a parent cursor representing the text of +a statement, and a number of child cursors for differing executions of the +statement, for example when different bind variable types or lengths are used. + +For example, with a table created as:: + + create table mytab (c1 varchar2(25), c2 varchar2(100), c3 number); + +You can use :meth:`~Cursor.setinputsizes()` to help reduce the number of child +cursors: + +.. code-block:: python + + sql = "insert into mytab (c1, c2) values (:1, :2)" + + cursor.setinputsizes(25, 15) + + s1 = "abc" + s2 = "def" + cursor.execute(sql, [s1, s2]) + + s1 = "aaaaaaaaaaaaaaaaaaaaaaaaa" + s2 = "z" + cursor.execute(sql, [s1, s2]) + +The :meth:`~Cursor.setinputsizes()` call indicates that the first value bound +will be a Python string of no more than 25 characters and the second value +bound will be a string of no more than 15 characters. If the data string +lengths exceed the :meth:`~Cursor.setinputsizes()` values, then python-oracledb +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 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: + +.. code-block:: python + + sql = "insert into mytab (c1, c2) values (:1, :2)" # statement to examine + + cursor.execute("select dbms_sql_translator.sql_id(:1) from dual", [sql]) + (sqlid,) = cursor.fetchone(); + print(sqlid) + +This might print a value like:: + + 6h6gj3ztw2wd8 + +Then, to find the SQL versions, run a query to see the child cursors. For +example: + +.. code-block:: python + + cursor.execute("""select child_number, reason + from v$sql_shared_cursor + where sql_id = :1 order by 1""", [sqlid]) + col_names = [c.name for c in cursor.description] + for row in cursor.fetchall(): + r = [dict(zip(col_names, row))] + print(r) + +With the earlier code that used :meth:`~Cursor.setinputsizes()` and inserted +different data lengths you might see:: + + [{'CHILD_NUMBER': 0, 'REASON': ' '}] + +However if :meth:`~Cursor.setinputsizes()` had not been used, you would see two +rows and REASON would include the text "Bind mismatch", for example:: + + [{'CHILD_NUMBER': 0, 'REASON': '039Bind mismatch(22)4x80132128 '}] + [{'CHILD_NUMBER': 1, 'REASON': '139Bind mismatch(22)4x80112832 '}] + .. _inputtypehandlers: @@ -678,6 +882,24 @@ statements, or even to enable new types to be bound directly. An input type handler is enabled by setting the attribute :attr:`Cursor.inputtypehandler` or :attr:`Connection.inputtypehandler`. +**Inserting NaN values as NULL in NUMBER columns** + +To insert NaN values as NULLs in a NUMBER column, use an input type handler +with an inconverter: + +.. code-block:: python + + def input_type_handler(cursor, value, arraysize): + if isinstance(value, float): + return cursor.var(oracledb.DB_TYPE_NUMBER, arraysize=arraysize, + inconverter=lambda x: None if math.isnan(x) else x) + + connection.inputtypehandler = input_type_handler + +Note that this is not needed for BINARY_FLOAT or BINARY_DOUBLE columns. + +**Binding Python Objects** + Input type handlers can be combined with variable converters to bind Python objects seamlessly: @@ -722,17 +944,19 @@ objects seamlessly: Binding Multiple Values to a SQL WHERE IN Clause ================================================ -To use a SQL IN clause with multiple values, use one bind variable per -value. You cannot directly bind a Python list or dictionary to a single bind -variable. For example, to use two values in an IN clause: +To use a SQL IN list with multiple values, use one bind variable placeholder +per value. You cannot directly bind a Python list or dictionary to a single +bind variable. For example, to use two values in an IN clause your code should +be like: .. code-block:: python + items = ["Smith", "Taylor"] cursor.execute(""" - select employee_id, first_name, last_name - from employees - where last_name in (:name1, :name2)""", - name1="Smith", name2="Taylor") + select employee_id, first_name, last_name + from employees + where last_name in (:1, :2)""", + items) for row in cursor: print(row) @@ -744,51 +968,95 @@ This gives the output:: (180, 'Winston', 'Taylor') If the query is executed multiple times with differing numbers of values, a -bind variable should be included for each possible value. When the statement is -executed but the maximum number of values has not been supplied, the value -``None`` can be bound for missing values. For example, if the query above is -used for up to 5 values, the code will be: +bind variable placeholder should be included in the SQL statement for each of +the maximum possible number of values. If the statement is executed with a +lesser number of data values, then bind ``None`` for missing values. For +example, if a query is used for up to five values, but only two values are used +in a particular execution, the code could be: .. code-block:: python + items = ["Smith", "Taylor", None, None, None] cursor.execute(""" - select employee_id, first_name, last_name - from employees - where last_name in (:name1, :name2, :name3, :name4, :name5)""", - name1="Smith", name2="Taylor", name3=None, name4=None, name5=None) + select employee_id, first_name, last_name + from employees + where last_name in (:1, :2, :3, :4, :5)""", + items) for row in cursor: print(row) -This will produce the same output as the original example. Reusing the same SQL -statement like this for a variable number of values, instead of constructing a -unique statement per set of values, allows best reuse of Oracle Database -resources. +This will produce the same output as the original example. + +Reusing the same SQL statement like this for a variable number of values, +instead of constructing a unique statement per set of values, allows best reuse +of Oracle Database resources. Additionally, if a statement with a large number +of bind variable placeholders is executed many times with varying string +lengths for each execution, then consider using :func:`Cursor.setinputsizes()` +to reduce Oracle Database's SQL ":ref:`version count `" for +the statement. For example, if the columns are VARCHAR2(25), then add this +before the :meth:`Cursor.execute()` call: + +.. code-block:: python + + cursor.setinputsizes(25,25,25,25,25) -However, if the statement is not going to be re-executed or the number of -values is only going to be known at runtime, then a SQL statement can be built -up as follows: +If other bind variables are required in the statement, adjust the bind variable +placeholder numbers appropriately: + +.. code-block:: python + + binds = [120] # employee id + binds += ["Smith", "Taylor", None, None, None] # IN list + cursor.execute(""" + select employee_id, first_name, last_name + from employees + where employee_id > :1 + and last_name in (:2, :3, :4, :5, :6)""", + binds) + for row in cursor: + print(row) + +If a statement containing WHERE IN is not going to be re-executed, or the +number of values is only going to be known at runtime, then a SQL statement can +be dynamically built: .. code-block:: python bind_values = ["Gates", "Marvin", "Fay"] - bind_names = [":" + str(i + 1) for i in range(len(bind_values))] - sql = "select employee_id, first_name, last_name from employees " + \ - "where last_name in (%s)" % (",".join(bind_names)) + bind_names = ",".join(":" + str(i + 1) for i in range(len(bind_values))) + sql = f"select first_name, last_name from employees where last_name in ({bind_names})" cursor.execute(sql, bind_values) for row in cursor: print(row) -A general solution for a larger number of values is to construct a SQL +Binding a Large Number of Items in an IN List +--------------------------------------------- + +The number of items in an IN list is limited to 65535 in Oracle Database 23ai, +and to 1000 in earlier versions. If you exceed the limit, the database will +return an error like ``ORA-01795: maximum number of expressions in a list is +65535``. + +To use more values in the IN clause list, you can add OR clauses like: + +.. code-block:: python + + sql = """select . . . + where key in (:0,:1,:2,:3,:4,:5,:6,:7,:8,:9,:10,:11,...) + or key in (:50,:51,:52,:53,:54,:55,:56,:57,:58,:59,...) + or key in (:100,:101,:102,:103,:104,:105,:106,:107,:108,:109,...)""" + +A more general solution for a larger number of values is to construct a SQL statement like:: SELECT ... WHERE col IN ( ) -The best way to do the '' depends -on how the data is initially represented and the number of items. You might -look at using CONNECT BY or at using a global temporary table. +The best way to do the '' depends on +how the data is initially represented and the number of items. For example you +might look at using a global temporary table. -One method is to use an Oracle collection with the ``TABLE()`` clause. For -example, if the following type was created:: +One method for large IN lists is to use an Oracle Database collection with the +``TABLE()`` clause. For example, if the following type was created:: SQL> CREATE OR REPLACE TYPE name_array AS TABLE OF VARCHAR2(25); 2 / @@ -807,15 +1075,27 @@ then the application could do: for row in cursor: print(row) -For efficiency, retain the return value of ``gettype()`` for reuse instead of -making repeated calls to get the type information. +When using this technique, it is important to review the database optimizer +plan to ensure it is efficient. + +Since this ``TABLE()`` solution uses an object type, there is a performance +impact because of the extra :ref:`round-trips ` required to get the +type information. Unless you have a large number of binds you may prefer one of +the previous solutions. For efficiency, retain the return value of +:meth:`Connection.gettype()` for reuse where possible instead of making +repeated calls to it. + +Some users employ the types SYS.ODCINUMBERLIST, SYS.ODCIVARCHAR2LIST, or +SYS.ODCIDATELIST instead of creating their own type, but this should be used +with the understanding that the database may remove these in a future version, +and that their size is 32K - 1. Binding Column and Table Names ============================== -Column and table names cannot be bound in SQL queries. You can concatenate -text to build up a SQL statement, but ensure that you use an Allow List or other -means to validate the data in order to avoid SQL Injection security issues: +Table names cannot be bound in SQL queries. You can concatenate text to build +up a SQL statement, but ensure that you use an Allow List or other means to +validate the data in order to avoid SQL Injection security issues: .. code-block:: python @@ -825,22 +1105,25 @@ means to validate the data in order to avoid SQL Injection security issues: raise Exception('Invalid table name') sql = f'select * from {table_name}' -Binding column names can be done either by using the above method or by using a -CASE statement. The example below demonstrates binding a column name in an +Binding column names can be done either by using a similar method, or by using +a CASE statement. The example below demonstrates binding a column name in an ORDER BY clause: .. code-block:: python sql = """ - SELECT * FROM departments - ORDER BY - CASE :bindvar - WHEN 'department_id' THEN DEPARTMENT_ID - ELSE MANAGER_ID - END""" + select * + from departments + order by + case :bindvar + when 'DEPARTMENT_ID' then + department_id + else + manager_id + end""" col_name = get_column_name() # Obtain a column name from the user cursor.execute(sql, [col_name]) Depending on the name provided by the user, the query results will be -ordered either by the column ``DEPARTMENT_ID`` or the column ``MANAGER_ID``. +ordered either by the column DEPARTMENT_ID or the column MANAGER_ID. diff --git a/doc/src/user_guide/connection_handling.rst b/doc/src/user_guide/connection_handling.rst index 4f347c22..4d2bc68a 100644 --- a/doc/src/user_guide/connection_handling.rst +++ b/doc/src/user_guide/connection_handling.rst @@ -5,8 +5,13 @@ Connecting to Oracle Database ***************************** Connections between python-oracledb and Oracle Database are used for executing -:ref:`SQL `, :ref:`PL/SQL `, and :ref:`SODA -`. +:ref:`SQL ` and :ref:`PL/SQL `, for calling +:ref:`SODA ` functions, for receiving database +:ref:`notifications ` and :ref:`messages `, and for +:ref:`starting and stopping ` the database. + +This chapter covers python-oracledb's synchronous programming model. For +discussion of asynchronous programming, see :ref:`asyncio`. By default, python-oracledb runs in a 'Thin' mode which connects directly to Oracle Database. This mode does not need Oracle Client libraries. However, @@ -27,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 @@ -67,10 +62,14 @@ Standalone Connections Standalone connections are database connections that do not use a python-oracledb connection pool. They are useful for simple applications that use a single connection to a database. Simple connections are created by -calling :meth:`oracledb.connect()` and passing a database username, the -database password for that user, and a 'data source name' :ref:`connection -string `. Python-oracledb also supports :ref:`external authentication -` and so passwords do not need to be in the application. +calling :meth:`oracledb.connect()` and passing: + +- A database username +- The database password for that user +- A 'data source name' connection string, see :ref:`connstr` + +Python-oracledb also supports :ref:`external authentication ` so +passwords do not need to be in the application. Creating a Standalone Connection -------------------------------- @@ -111,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 @@ -145,21 +124,36 @@ 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 +++++++++++++++++++ -Connections should be released when they are no longer needed. You may prefer +Connections should be released when they are no longer needed. You may prefer to let connections be automatically cleaned up when references to them go out -of scope. This lets python-oracledb close dependent resources in the correct -order: +of scope. This lets python-oracledb close dependent resources in the correct +order. For example, you can use a Python `context manager +`__ +``with`` block: .. code-block:: python - with oracledb.connect(user="hr", password=userpwd, - dsn="dbhost.example.com/orclpdb") as connection: + with oracledb.connect(user="hr", password=userpwd, dsn="myhostname/orclpdb") as connection: with connection.cursor() as cursor: - cursor.execute("insert into SomeTable values (:1, :2)", - (1, "Some string")) + cursor.execute("insert into SomeTable values (:1)", ("Some string")) connection.commit() This code ensures that once the block is completed, the connection is closed @@ -179,6 +173,9 @@ Alternatively, you can explicitly close a connection by calling. # close the connection connection.close() +If you explicitly close connections you may also need to close other resources +first. + .. _connerrors: Common Connection Errors @@ -220,7 +217,7 @@ Use the correct credentials If your username or password are not known by the database that you attempted to connect to, then you will get the error:: - ORA-01017: invalid username/password; logon denied + ORA-01017: invalid credential or not authorized; logon denied Find the correct username and password and try reconnecting. @@ -262,30 +259,62 @@ The solution is to use a valid service name in the connection string. You can: .. _connstr: -Connection Strings -================== +Oracle Net Services Connection Strings +====================================== -The data source name parameter ``dsn`` of :meth:`oracledb.connect()` and -:meth:`oracledb.create_pool()` is the Oracle Database connection string -that identifies which database service to connect to. The ``dsn`` string can be -one of: +The data source name parameter ``dsn`` of :meth:`oracledb.connect()`, +:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, and +:meth:`oracledb.create_pool_async()`, is the Oracle Database Oracle Net +Services Connection String (commonly abbreviated as "connection string") that +identifies which database service to connect to. The ``dsn`` value can be one +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 stored in a + :ref:`tnsnames.ora ` file +* An :ref:`LDAP URL ` +* 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`. + +For more information about naming methods, see the `Database Net Services +Administrator's Guide +`__. -* An Oracle Easy Connect string -* An Oracle Net Connect Descriptor string -* A Net Service Name mapping to a connect descriptor +.. note:: -For more information about naming methods, see `Oracle Net Service Reference -`__. + 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 ------------------------------------------ -An Easy Connect string is often the simplest connection string to use for the -data source name parameter ``dsn`` of :meth:`oracledb.connect()` and -:meth:`oracledb.create_pool()`. This method does not need configuration files -such as ``tnsnames.ora``. +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()`, +: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 @@ -306,65 +335,48 @@ 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 Plus -`__ 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 even allows some network -configuration options be set. This means that a :ref:`sqlnet.ora ` -file is not needed for some common connection scenarios. - -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. -.. _netservice: +For example, to set a connection timeout and keep-alive value: -Net Service Names for Connection Strings ----------------------------------------- +.. code-block:: python -Connect Descriptor Strings are commonly stored in a :ref:`tnsnames.ora -` file and associated with a Net Service Name. This name 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:: + connection = oracledb.connect(user="hr", password=userpwd, + dsn="dbhost.example.com/orclpdb?transport_connect_timeout=10&expire_time=2") - ORCLPDB = - (DESCRIPTION = - (ADDRESS = (PROTOCOL = TCP)(HOST = dbhost.example.com)(PORT = 1521)) - (CONNECT_DATA = - (SERVER = DEDICATED) - (SERVICE_NAME = orclpdb) - ) - ) -Then you could connect in python-oracledb Thin mode by using the following code: +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="orclpdb", - config_dir="/opt/oracle/config") + connection = oracledb.connect(user="hr", password=userpwd, + dsn="dbhost.example.com/orclpdb?pyo.stmtcachesize=50") -More options for how python-oracledb locates ``tnsnames.ora`` files is detailed -in :ref:`optnetfiles`. Note in python-oracledb Thick mode, the configuration -directory must be set during initialization, not at connection time. +See :ref:`pyoparams` for the usable attributes. -For more information about Net Service Names, see -`Database Net Services Reference -`__. +.. _conndescriptor: -Oracle Net Connect Descriptor Strings -------------------------------------- +Connect Descriptors +------------------- -Full Connect Descriptor strings can be embedded directly in python-oracledb -applications: +Connect Descriptors can be embedded directly in python-oracledb applications, +or referenced via a :ref:`TNS Alias `. + +An example of direct use is: .. code-block:: python @@ -377,9 +389,10 @@ applications: connection = oracledb.connect(user="hr", password=userpwd, dsn=dsn) -The :meth:`oracledb.ConnectParams()` and :meth:`ConnectParams.get_connect_string()` -functions can be used to construct a connect descriptor string from the -individual components, see :ref:`usingconnparams`. For example: +The :meth:`oracledb.ConnectParams()` and +:meth:`ConnectParams.get_connect_string()` functions can be used to construct a +connect descriptor from the individual components, see :ref:`usingconnparams`. +For example: .. code-block:: python @@ -389,8 +402,143 @@ individual components, see :ref:`usingconnparams`. 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: + +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()`, :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 = + (ADDRESS = (PROTOCOL = TCP)(HOST = dbhost.example.com)(PORT = 1521)) + (CONNECT_DATA = + (SERVER = DEDICATED) + (SERVICE_NAME = orclpdb) + ) + ) + +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") + +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 `. + +For more information about Net Service Names, see `Database Net Services +Reference `__. + +.. _ldapurl: + +LDAP URL Connection Strings +--------------------------- + +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 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: JDBC and Oracle SQL Developer Connection Strings ------------------------------------------------ @@ -412,215 +560,1938 @@ then use Oracle's Easy Connect syntax in python-oracledb: connection = oracledb.connect(user="hr", password=userpwd, dsn="dbhost.example.com:1521/orclpdb") -Alternatively, if a JDBC connection string uses an old-style Oracle Database -SID "system identifier", and the database does not have a service name:: +You may need to remove JDBC-specific parameters from the connection string and +use python-oracledb alternatives. + +If a JDBC connection string uses an old-style Oracle Database SID "system +identifier", and the database does not have a service name:: jdbc:oracle:thin:@hostname:port:sid -For example:: +For example:: + + jdbc:oracle:thin:@dbhost.example.com:1521:orcl + +then connect by using the ``sid`` parameter: + +.. code-block:: python + + connection = oracledb.connect(user="hr", password=userpwd, + host="dbhost.example.com", port=1521, sid="orcl") + +Alternatively, create a ``tnsnames.ora`` entry (see :ref:`optnetfiles`), for +example:: + + finance = + (DESCRIPTION = + (ADDRESS = (PROTOCOL = TCP)(HOST = dbhost.example.com)(PORT = 1521)) + (CONNECT_DATA = + (SID = ORCL) + ) + ) + +This can be referenced in python-oracledb: + +.. code-block:: python + + connection = oracledb.connect(user="hr", password=userpwd, dsn="finance") + +.. _connectdesckeywords: + +Oracle Net Connect Descriptor and Easy Connect Keywords +------------------------------------------------------- + +Easy Connect syntax is described in :ref:`easyconnect`. + +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 + + cs = "host.example.com:1522/orclpdb?pyo.stmtcachesize=30&pyo.mode=SYSDBA" + connection = oracledb.connect(user="hr", password=userpwd, dsn=cs) + +is the same as: + +.. 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: + +Using a File Centralized Configuration Provider +----------------------------------------------- + +The File Centralized Configuration Provider enables the storage and management +of Oracle Database connection information using local files. + +To use a File Centralized Configuration Provider, you must: + +1. Store the connection information in a JSON file on your local file system. + +2. Set the path to the file in the ``dsn`` parameter of connection and pool + creation methods. + +**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 key. The second column displays its description. 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. + + .. 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 `. + - 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 + +See the `Oracle Net Service Administrator’s Guide `__ for +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** + +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:: + + config-file://[?key=] + +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. + + * - 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. + +**File Configuration Provider Examples** + +An example of File Configuration Provider file syntax is:: + + { + "user": "scott", + "password": { + "type": "base64", + "value": "dGlnZXI=" + }, + "connect_descriptor": "dbhost.example.com:1522/orclpdb", + "pyo": { + "stmtcachesize": 30, + "min": 2, + "max": 10 + } + } + +This encodes the password as base64. See :ref:`ociobjstorageprovider` for +other password examples. Plaintext passwords are not supported. + +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": { + "connect_descriptor": "localhost/orclpdb" + }, + "testing": { + "connect_descriptor": "localhost/orclpdb", + "user": "scott", + "password": { + "type": "base64", + "value": "dGlnZXI=" + } + } + } + +If you have this configuration file in ``/opt/oracle/my-config2.json``, you +could use it like: + +.. code-block:: python + + connection = oracledb.connect(user="hr", password=userpwd, + dsn="config-file:///opt/oracle/my-config2.json?key=production") + + +.. _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: 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 + - 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 + * -