Add missing versionadded tag; make formatting consistent with other

files.
This commit is contained in:
Anthony Tuininga 2023-03-31 08:57:46 -06:00
parent 7f12d7339f
commit c2b32a54b9
1 changed files with 153 additions and 153 deletions

View File

@ -18,28 +18,30 @@ ConnectParams Methods
.. method:: ConnectParams.copy() .. method:: ConnectParams.copy()
Creates a copy of the ConnectParams instance and returns it. Creates a copy of the ConnectParams instance and returns it.
.. method:: ConnectParams.get_connect_string() .. method:: ConnectParams.get_connect_string()
Returns the connection string associated with the ConnectParams instance. Returns the connection string associated with the ConnectParams instance.
.. method:: ConnectParams.parse_connect_string(connect_string) .. method:: ConnectParams.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`` parameter can be an Easy Connect string, name-value 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 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. that are found in the connect string override any currently stored values.
.. method:: ConnectParams.parse_dsn_with_credentials(dsn) .. method:: ConnectParams.parse_dsn_with_credentials(dsn)
Parses a dsn in the form <user>/<password>@<connect_string> or in the form Parses a dsn in the form <user>/<password>@<connect_string> or in the form
<user>/<password> and returns a 3-tuple containing the parsed user, password <user>/<password> and returns a 3-tuple containing the parsed user,
and connect string. Empty strings are returned as the value ``None``. This is password and connect string. Empty strings are returned as the value
done automatically when a value is passed to the ``dsn`` parameter but no ``None``. This is done automatically when a value is passed to the ``dsn``
value is passed to the ``user`` password when creating a standalone parameter but no value is passed to the ``user`` password when creating a
connection or connection pool. standalone connection or connection pool.
.. versionadded:: 1.3.0
.. method:: ConnectParams.set(user=None, proxy_user=None, password=None, \ .. method:: ConnectParams.set(user=None, proxy_user=None, password=None, \
newpassword=None, wallet_password=None, access_token=None, host=None, \ newpassword=None, wallet_password=None, access_token=None, host=None, \
@ -51,7 +53,7 @@ ConnectParams Methods
matchanytag=None, config_dir=None, appcontext=[], shardingkey=[], supershardingkey=[], \ matchanytag=None, config_dir=None, appcontext=[], shardingkey=[], supershardingkey=[], \
debug_jdwp=None, handle=None) debug_jdwp=None, handle=None)
Sets one or more of the parameters. Sets one or more of the parameters.
.. _connparamsattr: .. _connparamsattr:
@ -61,276 +63,274 @@ ConnectParams Attributes
.. attribute:: ConnectParams.appcontext .. attribute:: ConnectParams.appcontext
This read-only attribute is a list that specifies the application context used by This read-only attribute is a list that specifies the application context
the connection. It is a list of 3-tuples that includes the namespace, name, and value. used by the connection. It is a list of 3-tuples that includes the
Each entry in the tuple is a string. namespace, name, and value. Each entry in the tuple is a string.
This attribute is only supported in the python-oracledb Thick mode. This attribute is only supported in the python-oracledb Thick mode.
.. attribute:: ConnectParams.cclass .. attribute:: ConnectParams.cclass
This read-only attribute is a string that specifies the connection class This read-only attribute is a string that specifies the connection class
to use for Database Resident Connection Pooling (DRCP). to use for Database Resident Connection Pooling (DRCP).
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.config_dir .. attribute:: ConnectParams.config_dir
This read-only attribute is a string that identifies the directory in which 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 the configuration files such as tnsnames.ora are found. The default is the
value of :attr:`defaults.config_dir`. value of :attr:`defaults.config_dir`.
This attribute is only supported in the python-oracledb Thin mode. This attribute is only supported in the python-oracledb Thin mode.
For the python-oracledb Thick mode, use the ``config_dir`` parameter of For the python-oracledb Thick mode, use the ``config_dir`` parameter of
:func:`oracledb.init_oracle_client`. :func:`oracledb.init_oracle_client`.
.. attribute:: ConnectParams.debug_jdwp .. attribute:: ConnectParams.debug_jdwp
This read-only attribute is a string with the format "host=<host>;port=<port>" This read-only attribute is a string with the format
that specifies the host and port of the PL/SQL debugger. This allows the "host=<host>;port=<port>" that specifies the host and port of the PL/SQL
Java Debug Wire Protocol (JDWP) to debug the PL/SQL code invoked by the debugger. This allows the Java Debug Wire Protocol (JDWP) to debug the
python-oracledb driver. The default value is the value of the environment PL/SQL code invoked by the python-oracledb driver. The default value is the
variable ``ORA_DEBUG_JDWP``. value of the environment variable ``ORA_DEBUG_JDWP``.
This attribute is only supported in the python-oracledb Thin mode. For This attribute is only supported in the python-oracledb Thin mode. For
the python-oracledb Thick mode, set the ``ORA_DEBUG_JDWP`` environment the python-oracledb Thick mode, set the ``ORA_DEBUG_JDWP`` environment
variable which has the same syntax. See :ref:`applntracing` for more variable which has the same syntax. See :ref:`applntracing` for more
information. information.
.. attribute:: ConnectParams.disable_oob .. attribute:: ConnectParams.disable_oob
This read-only attribute is a boolean that indicates whether out-of-band 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 breaks should be disabled. The default value is False. Note that this value
has no effect on Windows, which does not support this functionality. has no effect on Windows, which does not support this functionality.
This attribute is only supported in the python-oracledb Thin mode. This attribute is only supported in the python-oracledb Thin mode.
For the python-oracledb Thick mode, set the equivalent option in a For the python-oracledb Thick mode, set the equivalent option in a
``sqlnet.ora`` file. ``sqlnet.ora`` file.
.. attribute:: ConnectParams.edition .. attribute:: ConnectParams.edition
This read-only attribute is a string that specifies the edition to use This read-only attribute is a string that specifies the edition to use
for the connection. This attribute cannot be used simultaneously with the for the connection. This attribute cannot be used simultaneously with the
:attr:`ConnectParams.cclass` attribute. :attr:`ConnectParams.cclass` attribute.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.events .. attribute:: ConnectParams.events
This read-only attribute is a boolean that specifies whether the events mode This read-only attribute is a boolean that specifies whether the events
should be enabled. mode should be enabled.
This attribute is needed for continuous query notification (CQN) and high This attribute is needed for continuous query notification (CQN) and high
availability event notifications. The default value is False. availability event notifications. The default value is False.
This attribute is only supported in the python-oracledb Thick mode. This attribute is only supported in the python-oracledb Thick mode.
.. attribute:: ConnectParams.expire_time .. attribute:: ConnectParams.expire_time
This read-only attribute is an integer that returns the number of minutes This read-only attribute is an integer that returns the number of minutes
between the sending of keepalive probes. 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. 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 .. attribute:: ConnectParams.externalauth
This read-only attribute is a boolean that specifies whether external This read-only attribute is a boolean that specifies whether external
authentication should be used. The default value is False. authentication should be used. The default value is False.
For standalone connections, external authentication occurs when the For standalone connections, external authentication occurs when the
``user`` and ``password`` attributes are not used. If these attributes, ``user`` and ``password`` attributes are not used. If these attributes,
are not used, you can optionally set the ``externalauth`` attribute to are not used, you can optionally set the ``externalauth`` attribute to
True, which may aid code auditing. True, which may aid code auditing.
This attribute is only supported in the python-oracledb Thick mode. This attribute is only supported in the python-oracledb Thick mode.
.. attribute:: ConnectParams.host .. attribute:: ConnectParams.host
This read-only attribute is a string that returns the name or IP address of This read-only attribute is a string that returns the name or IP address of
the machine hosting the database. the machine hosting the database.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.https_proxy .. attribute:: ConnectParams.https_proxy
This read-only attribute is a string that returns the name or IP address of 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. a proxy host that is to be used for tunneling secure connections.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.https_proxy_port .. attribute:: ConnectParams.https_proxy_port
This read-only attribute is an integer that returns the port to be used to This read-only attribute is an integer that returns the port to be used to
communicate with the proxy host. communicate with the proxy host. The default value is 0.
The default value is 0.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.matchanytag .. attribute:: ConnectParams.matchanytag
This read-only attribute is a boolean that specifies whether any tag can be This read-only attribute is a boolean that specifies whether any tag can be
used when acquiring a connection from the pool. used when acquiring a connection from the pool. The default value is False.
The default value is False.
This attribute is only supported in the python-oracledb Thick mode. This attribute is only supported in the python-oracledb Thick mode.
.. attribute:: ConnectParams.mode .. attribute:: ConnectParams.mode
This read-only attribute is an integer that specifies the authorization mode This read-only attribute is an integer that specifies the authorization mode
to use. to use. The default value is :data:`~oracledb.AUTH_MODE_DEFAULT`.
The default value is :data:`~oracledb.AUTH_MODE_DEFAULT`.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.port .. attribute:: ConnectParams.port
This read-only attribute is an integer that returns the port number on which This read-only attribute is an integer that returns the port number on
the database listener is listening. The default value is 1521. which the database listener is listening. The default value is 1521.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.protocol .. attribute:: ConnectParams.protocol
This read-only attribute is a string that indicates whether unencrypted network This read-only attribute is a string that indicates whether unencrypted
traffic or encrypted network traffic (TLS) is used and it can have the value network traffic or encrypted network traffic (TLS) is used and it can have
tcp or tcps. the value "tcp" or "tcps". The default value is "tcp".
The default value is tcp.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.proxy_user .. attribute:: ConnectParams.proxy_user
This read-only attribute is a string that specifies the name of the proxy user to connect to. This read-only attribute is a string that specifies the name of the proxy
If this value is not specified, then it will be parsed out of the user if the user attribute user to connect to. If this value is not specified, then it will be parsed
is in the form "user[proxy_user]". 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. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.purity .. attribute:: ConnectParams.purity
This read-only attribute is an integer that returns the purity used for DRCP. This read-only attribute is an integer that returns the purity used for
When the value of this attribute is :attr:`oracledb.PURITY_DEFAULT`, then any DRCP. When the value of this attribute is :attr:`oracledb.PURITY_DEFAULT`,
standalone connection will use :attr:`oracledb.PURITY_NEW` and any pooled then any standalone connection will use :attr:`oracledb.PURITY_NEW` and any
connection will use :attr:`oracledb.PURITY_SELF`. The default value is pooled connection will use :attr:`oracledb.PURITY_SELF`. The default value
:data:`~oracledb.PURITY_DEFAULT`. is :data:`~oracledb.PURITY_DEFAULT`.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.retry_count .. attribute:: ConnectParams.retry_count
This read-only attribute is an integer that returns the number of times that a This read-only attribute is an integer that returns the number of times
connection attempt should be retried before the attempt is terminated. that a connection attempt should be retried before the attempt is
The default value is 0. terminated. The default value is 0.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.retry_delay .. attribute:: ConnectParams.retry_delay
This read-only attribute is an integer that returns the number of seconds to This read-only attribute is an integer that returns the number of seconds
wait before making a new connection attempt. to wait before making a new connection attempt. The default value is 0.
The default value is 0.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.server_type .. attribute:: ConnectParams.server_type
This read-only attribute is a string that returns the type of server connection This read-only attribute is a string that returns the type of server
that should be established. If specified, it should be one of `dedicated`, `shared`, connection that should be established. If specified, it should be one of
or `pooled`. `dedicated`, `shared`, or `pooled`.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.service_name .. attribute:: ConnectParams.service_name
This read-only attribute is a string that returns the service name of the database. 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. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.shardingkey .. attribute:: ConnectParams.shardingkey
This read-only attribute is a list that specifies a sequence of strings, numbers, This read-only attribute is a list that specifies a sequence of strings,
bytes, or dates that identify the database shard to connect to. numbers, bytes, or dates that identify the database shard to connect to.
This attribute is only supported in the python-oracledb Thick mode. This attribute is only supported in the python-oracledb Thick mode.
.. attribute:: ConnectParams.sid .. attribute:: ConnectParams.sid
This read-only attribute is a string that returns the SID of the database. 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. It is recommended to use the :attr:`ConnectParams.service_name` instead.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.ssl_server_cert_dn .. attribute:: ConnectParams.ssl_server_cert_dn
This read-only attribute is a string that returns the distinguished name (DN), This read-only attribute is a string that returns the distinguished name
which should be matched with the server. If this value is specified, then it is (DN), which should be matched with the server. If this value is specified,
used for any verification. Otherwise, the hostname will be used. 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` This value is ignored if the :attr:`~ConnectParams.ssl_server_dn_match`
attribute is not set to the value `True`. attribute is not set to the value `True`.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.ssl_server_dn_match .. attribute:: ConnectParams.ssl_server_dn_match
This read-only attribute is a boolean that indicates whether the server certificate This read-only attribute is a boolean that indicates whether the server
distinguished name (DN) should be matched in addition to the regular certificate distinguished name (DN) should be matched in addition to the
certificate verification that is performed. The default value is True. 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, Note that if the :attr:`~ConnectParams.ssl_server_cert_dn` attribute is not
then host name matching is performed instead. specified, then host name matching is performed instead.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.stmtcachesize .. attribute:: ConnectParams.stmtcachesize
This read-only attribute is an integer that identifies the initial size of This read-only attribute is an integer that identifies the initial size of
the statement cache. The default is the value of the statement cache. The default is the value of
:attr:`defaults.stmtcachesize`. :attr:`defaults.stmtcachesize`.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.supershardingkey .. attribute:: ConnectParams.supershardingkey
This read-only attribute is a list that specifies a sequence of strings, numbers, This read-only attribute is a list that specifies a sequence of strings,
bytes, or dates that identify the database shard to connect to. numbers, bytes, or dates that identify the database shard to connect to.
This attribute is only supported in python-oracledb Thick mode. This attribute is only supported in python-oracledb Thick mode.
.. attribute:: ConnectParams.tag .. attribute:: ConnectParams.tag
This read-only attribute is a string that identifies the type of connection that This read-only attribute is a string that identifies the type of connection
should be returned from a pool. that should be returned from a pool.
This attribute is only supported in python-oracledb Thick mode. This attribute is only supported in python-oracledb Thick mode.
.. attribute:: ConnectParams.tcp_connect_timeout .. attribute:: ConnectParams.tcp_connect_timeout
This read-only attribute is a float that indicates the maximum number of seconds This read-only attribute is a float that indicates the maximum number of
to wait for a connection to be established to the database host. seconds to wait for a connection to be established to the database host.
The default value is 60.0. The default value is 60.0.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.user .. attribute:: ConnectParams.user
This read-only attribute is a string that specifies the name of the user to This read-only attribute is a string that specifies the name of the user to
connect to. connect to.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.
.. attribute:: ConnectParams.wallet_location .. attribute:: ConnectParams.wallet_location
This read-only attribute is a string that specifies the directory where the This read-only attribute is a string that specifies the directory where the
wallet can be found. wallet can be found.
In python-oracledb Thin mode, this attribute is the directory containing the In python-oracledb Thin mode, this attribute is the directory containing
PEM-encoded wallet file, ewallet.pem. In python-oracledb Thick mode, this the PEM-encoded wallet file, ewallet.pem. In python-oracledb Thick mode,
attribute is the directory containing the file, cwallet.sso. this attribute is the directory containing the file, cwallet.sso.
This attribute is supported in the python-oracledb Thin and Thick modes. This attribute is supported in the python-oracledb Thin and Thick modes.