From e5a10834e078fd8a74913f06fe305b91fdbf7e65 Mon Sep 17 00:00:00 2001 From: Pebble94464 Date: Wed, 25 Dec 2024 00:04:17 +0000 Subject: [PATCH] Fix typos in DBAPI 2 documentation --- doc/dbapi2.rst | 55 +++++++++++++++++++++++++------------------------ jpype/dbapi2.py | 40 +++++++++++++++++------------------ 2 files changed, 48 insertions(+), 47 deletions(-) diff --git a/doc/dbapi2.rst b/doc/dbapi2.rst index 70b7167fd..060ef457f 100644 --- a/doc/dbapi2.rst +++ b/doc/dbapi2.rst @@ -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 @@ -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` @@ -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 @@ -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:: @@ -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 `_ is used to translate from a Python type into a Java type when setting a parameter. Once a result is produced, a `converter `_ can be used to translate the Java type back into a Python type. @@ -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 `_ property. @@ -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 `_ property on a Connection. .. autofunction:: jpype.dbapi2.SETTERS_BY_META @@ -177,7 +177,7 @@ the `setter `_ 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 @@ -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 @@ -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 @@ -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: @@ -266,9 +266,9 @@ 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` @@ -276,8 +276,8 @@ can directly use to communicate type information. ============= 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. @@ -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 `_. +.. The link to cursor.use above appears to be broken. Does cursor.use exist? ======== ======================== =================== ============== ================= =============== Group JDBC Type Default Getter Default Setter PyTypes Special Getter @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/jpype/dbapi2.py b/jpype/dbapi2.py index e391e3af8..32af7bca8 100644 --- a/jpype/dbapi2.py +++ b/jpype/dbapi2.py @@ -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)]] @@ -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() @@ -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. @@ -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. @@ -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 """ @@ -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() @@ -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 @@ -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: @@ -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 @@ -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. @@ -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) @@ -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. @@ -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) @@ -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). """