<commit_before># Copyright (C) 2005-2018 the SQLAlchemy authors and contributors
# <see AUTHORS file>
#
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php

"""

.. dialect:: oracle+cx_oracle
    :name: cx-Oracle
    :dbapi: cx_oracle
    :connectstring: oracle+cx_oracle://user:pass@host:port/dbname\
[?key=value&key=value...]
    :url: http://cx-oracle.sourceforge.net/

Additional Connect Arguments
----------------------------

When connecting with ``dbname`` present, the host, port, and dbname tokens are
converted to a TNS name using
the cx_oracle ``makedsn()`` function.  Otherwise, the host token is taken
directly as a TNS name.

Additional arguments which may be specified either as query string arguments
on the URL, or as keyword arguments to :func:`.create_engine()` are:

* ``arraysize`` - set the cx_oracle.arraysize value on cursors, defaulted
  to 50.  This setting is significant with cx_Oracle as the contents of LOB
  objects are only readable within a "live" row (e.g. within a batch of
  50 rows).

* ``auto_convert_lobs`` - defaults to True; See :ref:`cx_oracle_lob`.

* ``coerce_to_unicode`` - see :ref:`cx_oracle_unicode` for detail.

* ``coerce_to_decimal`` - see :ref:`cx_oracle_numeric` for detail.

* ``mode`` - This is given the string value of SYSDBA or SYSOPER, or
  alternatively an integer value.  This value is only available as a URL query
  string argument.

* ``threaded`` - enable multithreaded access to cx_oracle connections.
  Defaults to ``True``.  Note that this is the opposite default of the
  cx_Oracle DBAPI itself.

* ``service_name`` - An option to use connection string (DSN) with
  ``SERVICE_NAME`` instead of ``SID``. It can't be passed when a ``database``
  part is given.
  E.g. ``oracle+cx_oracle://scott:tiger@host:1521/?service_name=hr``
  is a valid url. This value is only available as a URL query string argument.

  .. versionadded:: 1.0.0

.. _cx_oracle_unicode:

Unicode
-------

The cx_Oracle DBAPI as of version 5 fully supports unicode, and has the
ability to return string results as Python unicode objects natively.

When used in Python 3, cx_Oracle returns all strings as Python unicode objects
(that is, plain ``str`` in Python 3).  In Python 2, it will return as Python
unicode those column values that are of type ``NVARCHAR`` or ``NCLOB``.  For
column values that are of type ``VARCHAR`` or other non-unicode string types,
it will return values as Python strings (e.g. bytestrings).

The cx_Oracle SQLAlchemy dialect presents several different options for the use
case of receiving ``VARCHAR`` column values as Python unicode objects under
Python 2:

* When using Core expression objects as well as the ORM, SQLAlchemy's
  unicode-decoding services are available, which are established by
  using either the :class:`.Unicode` datatype or by using the
  :class:`.String` datatype with :paramref:`.String.convert_unicode` set
  to True.

* When using raw SQL strings, typing behavior can be added for unicode
  conversion using the :func:`.text` construct::

    from sqlalchemy import text, Unicode
    result = conn.execute(
        text("select username from user").columns(username=Unicode))

* Otherwise, when using raw SQL strings sent directly to an ``.execute()``
  method without any Core typing behavior added, the flag
  ``coerce_to_unicode=True`` flag can be passed to :func:`.create_engine`
  which will add an unconditional unicode processor to cx_Oracle for all
  string values::

    engine = create_engine("oracle+cx_oracle://dsn", coerce_to_unicode=True)

  The above approach will add significant latency to result-set fetches
  of plain string values.

<commit_msg>Document how to opt-out of NCHAR for cx_Oracle<commit_after># Copyright (C) 2005-2018 the SQLAlchemy authors and contributors
# <see AUTHORS file>
#
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php

"""

.. dialect:: oracle+cx_oracle
    :name: cx-Oracle
    :dbapi: cx_oracle
    :connectstring: oracle+cx_oracle://user:pass@host:port/dbname\
[?key=value&key=value...]
    :url: http://cx-oracle.sourceforge.net/

Additional Connect Arguments
----------------------------

When connecting with ``dbname`` present, the host, port, and dbname tokens are
converted to a TNS name using
the cx_oracle ``makedsn()`` function.  Otherwise, the host token is taken
directly as a TNS name.

Additional arguments which may be specified either as query string arguments
on the URL, or as keyword arguments to :func:`.create_engine()` are:

* ``arraysize`` - set the cx_oracle.arraysize value on cursors, defaulted
  to 50.  This setting is significant with cx_Oracle as the contents of LOB
  objects are only readable within a "live" row (e.g. within a batch of
  50 rows).

* ``auto_convert_lobs`` - defaults to True; See :ref:`cx_oracle_lob`.

* ``coerce_to_unicode`` - see :ref:`cx_oracle_unicode` for detail.

* ``coerce_to_decimal`` - see :ref:`cx_oracle_numeric` for detail.

* ``mode`` - This is given the string value of SYSDBA or SYSOPER, or
  alternatively an integer value.  This value is only available as a URL query
  string argument.

* ``threaded`` - enable multithreaded access to cx_oracle connections.
  Defaults to ``True``.  Note that this is the opposite default of the
  cx_Oracle DBAPI itself.

* ``service_name`` - An option to use connection string (DSN) with
  ``SERVICE_NAME`` instead of ``SID``. It can't be passed when a ``database``
  part is given.
  E.g. ``oracle+cx_oracle://scott:tiger@host:1521/?service_name=hr``
  is a valid url. This value is only available as a URL query string argument.

  .. versionadded:: 1.0.0

.. _cx_oracle_unicode:

Unicode
-------

The cx_Oracle DBAPI as of version 5 fully supports unicode, and has the
ability to return string results as Python unicode objects natively.

When used in Python 3, cx_Oracle returns all strings as Python unicode objects
(that is, plain ``str`` in Python 3).  In Python 2, it will return as Python
unicode those column values that are of type ``NVARCHAR`` or ``NCLOB``.  For
column values that are of type ``VARCHAR`` or other non-unicode string types,
it will return values as Python strings (e.g. bytestrings).

The cx_Oracle SQLAlchemy dialect presents several different options for the use
case of receiving ``VARCHAR`` column values as Python unicode objects under
Python 2:

* When using Core expression objects as well as the ORM, SQLAlchemy's
  unicode-decoding services are available, which are established by
  using either the :class:`.Unicode` datatype or by using the
  :class:`.String` datatype with :paramref:`.String.convert_unicode` set
  to True.

* When using raw SQL strings, typing behavior can be added for unicode
  conversion using the :func:`.text` construct::

    from sqlalchemy import text, Unicode
    result = conn.execute(
        text("select username from user").columns(username=Unicode))

* Otherwise, when using raw SQL strings sent directly to an ``.execute()``
  method without any Core typing behavior added, the flag
  ``coerce_to_unicode=True`` flag can be passed to :func:`.create_engine`
  which will add an unconditional unicode processor to cx_Oracle for all
  string values::

    engine = create_engine("oracle+cx_oracle://dsn", coerce_to_unicode=True)

  The above approach will add significant latency to result-set fetches
  of plain string values.

Sending String Values as Unicode or Non-Unicode
------------------------------------------------

As of SQLAlchemy 1.2.2, the cx_Oracle dialect unconditionally calls
``setinputsizes()`` for bound values that are passed as Python unicode objects.
In Python 3, all string values are Unicode; for cx_Oracle, this corresponds to
``cx_Oracle.NCHAR`` being passed to ``setinputsizes()`` for that parameter.
In some edge cases, such as passing format specifiers for
the ``trunc()`` function, Oracle does not accept these as NCHAR::

    from sqlalchemy import func

    conn.execute(
        func.trunc(func.sysdate(), 'dd')
    )

In these cases, an error as follows may be raised::

    ORA-01899: bad precision specifier

When this error is encountered, it may be necessary to pass the string value
with an explicit non-unicode type::

    from sqlalchemy import func
    from sqlalchemy import literal
    from sqlalchemy import String

    conn.execute(
        func.trunc(func.sysdate(), literal('dd', String))
    )


{'fraction_non_alphanumeric': 0.09943648743836582, 'fraction_numerical': 0.006691711669405964, 'mean_word_length': 3.96156086196855, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4253351', 'n_tokens_mistral': 2574, 'n_tokens_neox': 2392, 'n_words': 1065}