Rename KafkaError .is_txn_abortable() to .txn_requires_abort()

edenhill · edenhill · commit 086d5c0ec47f · 2020-03-12T14:11:22.000+01:00
diff --git a/confluent_kafka/src/Producer.c b/confluent_kafka/src/Producer.c
@@ -698,8 +698,8 @@ static PyMethodDef Producer_methods[] = {
           "\n"
           "  :raises: KafkaError: Use exc.args[0].retriable() to check if the\n"
           "           operation may be retried, or\n"
-          "           exc.args[0].txn_abortable() if the current transaction\n"
-          "           has failed and must be aborted by calling\n"
+          "           exc.args[0].txn_requires_abort() if the current\n"
+          "           transaction has failed and must be aborted by calling\n"
           "           abort_transaction() and then start a new transaction\n"
           "           with begin_transaction().\n"
           "           Treat any other error as a fatal error.\n"
@@ -734,8 +734,8 @@ static PyMethodDef Producer_methods[] = {
           "\n"
           "  :raises: KafkaError: Use exc.args[0].retriable() to check if the\n"
           "           operation may be retried, or\n"
-          "           exc.args[0].txn_abortable() if the current transaction\n"
-          "           has failed and must be aborted by calling\n"
+          "           exc.args[0].txn_requires_abort() if the current\n"
+          "           transaction has failed and must be aborted by calling\n"
           "           abort_transaction() and then start a new transaction\n"
           "           with begin_transaction().\n"
           "           Treat any other error as a fatal error.\n"
@@ -747,7 +747,7 @@ static PyMethodDef Producer_methods[] = {
           "\n"
           "  Aborts the current transaction.\n"
           "  This function should also be used to recover from non-fatal\n"
-          "  abortable transaction errors, when KafkaError.txn_abortable()\n"
+          "  abortable transaction errors when KafkaError.txn_requires_abort()\n"
           "  is True.\n"
           " \n"
           "  Any outstanding messages will be purged and fail with\n"
diff --git a/confluent_kafka/src/confluent_kafka.c b/confluent_kafka/src/confluent_kafka.c
@@ -64,8 +64,8 @@ typedef struct {
 		      * Else falls back on err2str(). */
         int   fatal; /**< Set to true if a fatal error. */
         int   retriable; /**< Set to true if operation is retriable. */
-        int   txn_abortable; /**< Set to true if this is an abortable
-                              *   transaction error. */
+        int   txn_requires_abort; /**< Set to true if this is an abortable
+                                   *   transaction error. */
 } KafkaError;
 
 
@@ -99,8 +99,9 @@ static PyObject *KafkaError_retriable (KafkaError *self, PyObject *ignore) {
         return ret;
 }
 
-static PyObject *KafkaError_txn_abortable (KafkaError *self, PyObject *ignore) {
-        PyObject *ret = self->txn_abortable ? Py_True : Py_False;
+static PyObject *
+KafkaError_txn_requires_abort (KafkaError *self, PyObject *ignore) {
+        PyObject *ret = self->txn_requires_abort ? Py_True : Py_False;
         Py_INCREF(ret);
         return ret;
 }
@@ -151,12 +152,15 @@ static PyMethodDef KafkaError_methods[] = {
           "  :rtype: bool\n"
           "\n"
         },
-        { "txn_abortable", (PyCFunction)KafkaError_txn_abortable, METH_NOARGS,
-          "  :returns: True if the error is an abortable transaction error, "
-          "allowing the application to abort the current transaction with "
+        { "txn_requires_abort", (PyCFunction)KafkaError_txn_requires_abort,
+          METH_NOARGS,
+          "  :returns: True if the error is an abortable transaction error "
+          "in which case application must abort the current transaction with "
           "abort_transaction() and start a new transaction with "
-          "begin_transaction(). This will only return true for errors from "
-          "the transactional producer API.\n"
+          "begin_transaction() if it wishes to proceed with "
+          "transactional operations. "
+          "This will only return true for errors from the transactional\n"
+          "producer API.\n"
           "  :rtype: bool\n"
           "\n"
         },
@@ -305,7 +309,7 @@ static void KafkaError_init (KafkaError *self,
 	self->code = code;
         self->fatal = 0;
         self->retriable = 0;
-        self->txn_abortable = 0;
+        self->txn_requires_abort = 0;
 	if (str)
 		self->str = strdup(str);
 	else
@@ -364,7 +368,7 @@ PyObject *KafkaError_new_from_error_destroy (rd_kafka_error_t *error) {
 
         kerr->fatal = rd_kafka_error_is_fatal(error);
         kerr->retriable = rd_kafka_error_is_retriable(error);
-        kerr->txn_abortable = rd_kafka_error_is_txn_abortable(error);
+        kerr->txn_requires_abort = rd_kafka_error_txn_requires_abort(error);
         rd_kafka_error_destroy(error);
 
         return (PyObject *)kerr;
diff --git a/docs/index.rst b/docs/index.rst
@@ -257,7 +257,7 @@ using :py:meth:`confluent_kafka.Producer.abort_transaction()` and optionally
 start a new transaction by calling
 :py:meth:`confluent_kafka.Producer.begin_transaction()`.
 Whether an error is abortable or not is detected by calling
-:py:meth:`confluent_kafka.KafkaError.txn_abortable()`.
+:py:meth:`confluent_kafka.KafkaError.txn_requires_abort()`.
 
 **Fatal errors**
 
@@ -295,7 +295,7 @@ neither the retriable or abortable flags set, as fatal.
            if e.args[0].retriable():
               # retriable error, try again
               continue
-           elif e.args[0].txn_abortable():
+           elif e.args[0].txn_requires_abort():
               # abort current transaction, begin a new transaction,
               # and rewind the consumer to start over.
               producer.abort_transaction()
diff --git a/tests/test_Producer.py b/tests/test_Producer.py
@@ -200,15 +200,15 @@ def test_transaction_api():
     assert ex.value.args[0].code() == KafkaError._TIMED_OUT
     assert ex.value.args[0].retriable() is True
     assert ex.value.args[0].fatal() is False
-    assert ex.value.args[0].txn_abortable() is False
+    assert ex.value.args[0].txn_requires_abort() is False
 
     # Any subsequent APIs will fail since init did not succeed.
     with pytest.raises(KafkaException) as ex:
         p.begin_transaction()
     assert ex.value.args[0].code() == KafkaError._STATE
     assert ex.value.args[0].retriable() is False
     assert ex.value.args[0].fatal() is False
-    assert ex.value.args[0].txn_abortable() is False
+    assert ex.value.args[0].txn_requires_abort() is False
 
     consumer = Consumer({"group.id": "testgroup"})
     group_metadata = consumer.consumer_group_metadata()
@@ -220,18 +220,18 @@ def test_transaction_api():
     assert ex.value.args[0].code() == KafkaError._STATE
     assert ex.value.args[0].retriable() is False
     assert ex.value.args[0].fatal() is False
-    assert ex.value.args[0].txn_abortable() is False
+    assert ex.value.args[0].txn_requires_abort() is False
 
     with pytest.raises(KafkaException) as ex:
         p.commit_transaction(0.5)
     assert ex.value.args[0].code() == KafkaError._STATE
     assert ex.value.args[0].retriable() is False
     assert ex.value.args[0].fatal() is False
-    assert ex.value.args[0].txn_abortable() is False
+    assert ex.value.args[0].txn_requires_abort() is False
 
     with pytest.raises(KafkaException) as ex:
         p.abort_transaction(0.5)
     assert ex.value.args[0].code() == KafkaError._STATE
     assert ex.value.args[0].retriable() is False
     assert ex.value.args[0].fatal() is False
-    assert ex.value.args[0].txn_abortable() is False
+    assert ex.value.args[0].txn_requires_abort() is False
