Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix typos in DBAPI 2 documentation #1251

Merged
merged 1 commit into from
Jan 20, 2025
+48 −47
Merged

Fix typos in DBAPI 2 documentation #1251

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 28 additions & 27 deletions doc/dbapi2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ JPype DBAPI2 Guide
`Introduction`
==============

One common use of JPype is to provide access to databases used JDBC. The JDBC
One common use of JPype is to provide access to databases using JDBC. The JDBC
API is well established, very capable, and supports most databases.
JPype can be used to access JDBC both directly or through the use of the Python
DBAPI2 as layed (see PEP-0249_). Unfortunately, the Python API leaves a lot of
Expand All @@ -15,7 +15,7 @@ The JPype dbapi2 module provides our implementation of this Python API.
Normally the Python API has to deal with two different type systems, Python
and SQL. When using JDBC, we have the added complexity that Java types are
used to communicate with the driver. We have introduced concepts appropriate
to handle this addition complexity.
to handle this additional complexity.


`Module Interface`
Expand Down Expand Up @@ -49,7 +49,7 @@ These values are constants.
The threadsafety level is 2 meaning "Threads may share the module and
connections". But the actual threading level depends on the driver
implementation that JDBC is connected to. Connections for many databases
are synchronized so they can be shared, but threads must execute statement
are synchronized so they can be shared, but threads must execute statements
in series. Connections in the module are implemented in Python and
have per object resources that cannot be shared. Attempting to use a
connection with a thread other than the thread that created it will
Expand Down Expand Up @@ -91,7 +91,7 @@ exceptions:
.. autoclass:: jpype.dbapi2.ProgrammingError
.. autoclass:: jpype.dbapi2.NotSupportedError

Python exceptions are more fine grain than JDBC exceptions. Whereever possible
Python exceptions are more fine grain than JDBC exceptions. Wherever possible
we have redirected the Java exception to the nearest Python exception. However,
there are cases in which the Java exception may appear. Those exceptions
inherit from `:py:class:jpype.dbapi2.Error`. This is the exception inheritance layout::
Expand Down Expand Up @@ -127,7 +127,7 @@ Type Access

JPype dbapi2 provides two different maps which serve to convert data
between Python and SQL types. When setting parameters and fetching
results, Java types are used. The connection provides to maps for converting
results, Java types are used. The connection provides two maps for converting
the types of parameters. An `adapter <adapters_>`_ is used to translate from a Python
type into a Java type when setting a parameter. Once a result is produced,
a `converter <converters_>`_ can be used to translate the Java type back into a Python type.
Expand All @@ -143,13 +143,13 @@ adapters_
Whenever a Python type is passed to a statement, it must first be converted
to the appropriate Java type. This can be accomplished in a few ways. The
user can manually convert to the correct type by constructing a Java object or
applying the JPype casting operator. Some Java types have built in implicit
applying the JPype casting operator. Some Java types have built-in implicit
conversions from the corresponding type. For all other conversions, an adapter.
An adapter is defined as a type to convert from and a conversion function which
takes a single argument that returns a Java object.

The adapter maps are stored in the connection. The adapter map can be
supplied when calling `connect`_ , or added to the map later
supplied when calling `connect`_, or added to the map later
through the `adapters <connection.adapters_>`_ property.


Expand All @@ -159,14 +159,14 @@ setters_
--------

A setter transfers the Java type into a SQL parameter. There are multiple
types can an individual parameter may accept. The type of setter is determined
types that an individual parameter may accept. The type of setter is determined
by the JDBC type. Each individual JDBC type can have its own setter. Not
every database supports the same setter. There is a default setter may that
would work for most purposes. Setters can also be set individually using
every database supports the same setter. There is a default setter that
should work for most purposes. Setters can also be set individually using
the ``types`` argument to the ``.execute*()`` methods. The setter is a
function which processes the database metadata into a type.

Setters can supplied as a map to `connect`_ or by accessing
Setters can be supplied as a map to `connect`_ or by accessing
the `setter <connection.setters_>`_ property on a Connection.

.. autofunction:: jpype.dbapi2.SETTERS_BY_META
Expand All @@ -177,7 +177,7 @@ the `setter <connection.setters_>`_ property on a Connection.
converters_
-----------

When a result is fetched the database, it is returned as Jave type. This Java
When a result is fetched from the database it is returned as a Java type. This Java
type then has a converter applied. Converters are stored in a map holding the
type as key and a converter function that takes one argument and returns the desired type.
The default converter map will convert all types to Python. This can be
Expand Down Expand Up @@ -207,7 +207,7 @@ function that uses the metadata to find the most appropriate type.
`Connection Objects`_
=====================

A Connection object can be created using the using `connect`_ function. Once a
A Connection object can be created by using the `connect`_ function. Once a
connection is established the resulting Connection contains the following.

.. autoclass:: jpype.dbapi2.Connection
Expand All @@ -230,7 +230,7 @@ transaction support is implemented (see also the connection's
:members:


Cursors can act as an iterator. So to get the contents of table one
Cursors can act as an iterator. So to get the contents of a table one
could use code like:

.. code-block:: python
Expand All @@ -253,7 +253,7 @@ the `.execute*()` method are untyped. When the database module sees
a Python string object, it doesn't know if it should be bound as a
simple `CHAR` column, as a raw `BINARY` item, or as a `DATE`.

This is less of a problem in JPype dbapi2 than in a typically
This is less of a problem in JPype dbapi2 than in a typical
dbapi driver as we have strong typing backing the connection,
but we are still required to supply methods to construct individual
SQL types. These functions are:
Expand All @@ -266,18 +266,18 @@ SQL types. These functions are:
.. autofunction:: jpype.dbapi2.TimestampFromTicks
.. autofunction:: jpype.dbapi2.Binary

For the most part these constructors are largely redundant as
For the most part these constructors are largely redundant because
adapters can provide the same functionality and Java types
can directly use to communicate type information.
can be used directly to communicate type information.

.. `JDBC Types`

`JDBC Types`_
=============

In the Python DBAPI2, the SQL type system is normally reduced to a subset
of the SQL types by mapping multiple types together for example ``STRING``
covers the types `STRING`, `CHAR`, `NCHAR` , `NVARCHAR` , `VARCHAR`,
of the SQL types by mapping multiple types together. For example, ``STRING``
covers types `STRING`, `CHAR`, `NCHAR` , `NVARCHAR` , `VARCHAR`,
and `OTHER`. JPype dbapi2 supports both the recommended Python types and
the fine grain JDBC types. Each type is represented by an object
of type JBDCType.
Expand All @@ -288,10 +288,11 @@ of type JBDCType.
The following types are defined with the correspond Python grouping, the
default setter, getter, and Python type. For types that support more than
one type of getter, the special getter can be applied as the converter for
the type. For example, the defaulf configuration has ``getter[BLOB] = BINARY.get``,
the type. For example, the default configuration has ``getter[BLOB] = BINARY.get``,
to get the Blob type use ``getter[BLOB] = BLOB.get`` or specify it when
calling `use <cursor.use_>`_.

.. The link to cursor.use above appears to be broken. Does cursor.use exist?

======== ======================== =================== ============== ================= ===============
Group JDBC Type Default Getter Default Setter PyTypes Special Getter
Expand Down Expand Up @@ -365,7 +366,7 @@ A user can declare a new type using ``JDBCType``. The arguments are the name of
new type which must match a SQL typename. Use ``typeinfo`` on the connection to
get the list of available types.

It may necessary to define a custom getter function which defining a new type
It may be necessary to define a custom getter function when defining a new type
so that the custom return type accurately reflects the column type.

.. code-block:: python
Expand All @@ -381,11 +382,11 @@ so that the custom return type accurately reflects the column type.
Interactions with prepared statements
-------------------------------------

Certain calls can be problematic for dbapi2 depending on driver. In
Certain calls can be problematic for dbapi2 depending on the driver. In
particular, SQL calls which invalidate the state of the connection will issue
an exception when the connection is used. In HSQLDB the statement
``cur.execute('shutdown')`` invalidates the connection which when the statement
is then automatically closed will then produce an exception.
an exception when the connection is used. For example, when using HSQLDB, the
statement ``cur.execute('shutdown')`` will invalidate and close the connection,
causing an exception to be raised.

This exception is due to a conflict between dbapi2, Java, and HSQLDB
specifications. Dbapi2 requires that statements be executed as prepared
Expand All @@ -394,7 +395,7 @@ connection is already closed, and HSQLBD sets the ``isValid`` to false but not
``isClosed``. Thus executing a shutdown through dbapi2 would be expected to
close the prepared statement on an invalid connection resulting in an error.

We can address these sort of driver specific behaviors by applying a customizer
We can address these sorts of driver specific behaviors by applying a customizer
to the Java class to add additional behaviors.

.. code-block:: python
Expand All @@ -416,7 +417,7 @@ Conclusion
==========

This wraps up the JPype dbapi2 module. Because JDBC supports many different
dataase drivers, not every behavior is defined on every driver. Consult the
database drivers, not every behavior is defined on every driver. Consult the
driver specific information to determine what is available.

The dbapi2 does not fully cover all of the capabilities of the JDBC driver. To
Expand Down
40 changes: 20 additions & 20 deletions jpype/dbapi2.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,8 +244,8 @@ def SETTERS_BY_META(cx, meta, col, ptype):
""" Option for setters to use the metadata of the parameters.

On some databases this option is useless as they do not track parameter
types. This method can be cached for faster performance when lots of
parameters. Usually types can only be determined accurately on inserts
types. This method can be cached for faster performance when the are lots
of parameters. Usually types can only be determined accurately on inserts
into defined columns.
"""
return _default_map[_registry[meta.getParameterType(col + 1)]]
Expand Down Expand Up @@ -282,12 +282,12 @@ def GETTERS_BY_TYPE(cx, meta, idx):


def GETTERS_BY_NAME(cx, meta, idx):
""" Option to getters to determine column type by the column name.
""" Option for getters to determine column type by the column name.

This option uses the column name to select the type. It looks up
the column type name, converts it to uppercase, and then searches
for a matchine type. It falls back to the type code meta information if
the typename can not be found in the registery. New types can be created
for a matching type. It falls back to the type code meta information if
the type name cannot be found in the registry. New types can be created
using JDBCType for database specific types such as ``JSON``.
"""
name = str(meta.getColumnTypeName(idx + 1)).upper()
Expand Down Expand Up @@ -388,7 +388,7 @@ def connect(dsn, *, driver=None, driver_args=None,
dsn (str): The database connection string for JDBC.
driver (str, optional): A JDBC driver to load.
driver_args: Arguments to the driver. This may either be a dict,
java.util.Properties. If not supplied, kwargs are used as as the
java.util.Properties. If not supplied, kwargs are used as the
parameters for the JDBC connection.
*kwargs: Arguments to the driver if not supplied as
driver_args.
Expand Down Expand Up @@ -432,7 +432,7 @@ def connect(dsn, *, driver=None, driver_args=None,
class Connection(object):
""" Connection provides access to a JDBC database.

Connections are managed and can be as part of a Python with statement.
Connections are managed and can be used as part of a Python 'with' statement.
Connections close automatically when they are garbage collected, at the
end of a with statement scope, or when manually closed. Once a connection
is closed all operations using the database will raise an Error.
Expand Down Expand Up @@ -528,7 +528,7 @@ def getters(self, v):

@property
def setters(self):
""" Setter are used to set parameters to ``.execute*()`` methods.
""" Setters are used to set parameters to ``.execute*()`` methods.

Setters should be a function taking (connection, meta, col, type) -> JDBCTYPE
"""
Expand Down Expand Up @@ -578,7 +578,7 @@ def close(self):
def commit(self):
"""Commit any pending transaction to the database.

Calling commit on a cooonection that does not support the operation
Calling commit on a connection that does not support the operation
will raise NotSupportedError.
"""
self._validate()
Expand All @@ -593,8 +593,8 @@ def rollback(self):
"""Rollback the transaction.

This method is optional since not all databases provide transaction
support. Calling rollback on a cooonection that does not support will
raise NotSupportedError.
support. Calling rollback on a connection that does not support it
will raise NotSupportedError.

In case a database does provide transactions this method causes the
database to roll back to the start of any pending transaction. Closing
Expand Down Expand Up @@ -839,8 +839,8 @@ def resultSet(self):

@property
def parameters(self):
""" (extension) Parameters is read-only attribute is a sequence of
6-item sequences.
""" (extension) Parameters is a read-only attribute. It is a sequence
of 6-item sequences.

Each of these sequences contains information describing one result
column:
Expand Down Expand Up @@ -869,7 +869,7 @@ def parameters(self):

@property
def description(self):
""" Description is read-only attribute is a sequence of 7-item
""" Description is a read-only attribute. It is a sequence of 7-item
sequences.

Each of these sequences contains information describing one result
Expand Down Expand Up @@ -909,7 +909,7 @@ def rowcount(self):
.execute*() affected (for DML statements like UPDATE or INSERT).

The attribute is -1 in case no .execute*() has been performed on the
cursor or the rowcount of the last operation is cannot be determined by
cursor or the rowcount of the last operation cannot be determined by
the interface. JDBC does not support getting the number of rows
returned from SELECT, so for most drivers rowcount will be -1 after a
SELECT statement.
Expand Down Expand Up @@ -1031,7 +1031,7 @@ def execute(self, operation, parameters=None, *, types=None, keys=False):
Parameters:
operation (str): A statement to be executed.
parameters (list, optional): A list of parameters for the statement.
The number of parameters much match the number required by the
The number of parameters must match the number required by the
statement or an Error will be raised.
keys (bool, optional): Specify if the keys should be available to
retrieve. (Default False)
Expand Down Expand Up @@ -1088,11 +1088,11 @@ def executemany(self, operation, seq_of_parameters, *, types=None, keys=False):
Args:
operation (str): A statement to be executed.
seq_of_parameters (list, optional): A list of lists of parameters
for the statement. The number of parameters much match the number
for the statement. The number of parameters must match the number
required by the statement or an Error will be raised.
keys (bool, optional): Specify if the keys should be available to
retrieve. (Default False) For drivers that do not support
batch updates only that last key will be returned.
batch updates only the last key will be returned.

Returns:
This cursor.
Expand Down Expand Up @@ -1353,7 +1353,7 @@ def Time(hour, minute, second):


def Timestamp(year, month, day, hour, minute, second, nano=0):
""" This function constructs an object holding a time stamp value. """
""" This function constructs an object holding a timestamp value. """
return _jpype.JClass('java.sql.Timestamp')(year - 1900, month - 1, day, hour, minute, second, nano)


Expand All @@ -1378,7 +1378,7 @@ def TimeFromTicks(ticks):

def TimestampFromTicks(ticks):
"""
This function constructs an object holding a time stamp value from the
This function constructs an object holding a timestamp value from the
given ticks value (number of seconds since the epoch; see the documentation
of the standard Python time module for details).
"""
Expand Down