[CLIENT-4702] Convert docstring code examples to doctest format and validate them

.github/workflows/smoke-tests.yml

@@ -360,6 +360,12 @@ jobs:
           "3.13",
           "3.14"
         ]
+        type: [
+          regular
+        ]
+        include:
+          - type: doctest
+            py-version: '3.12'
       fail-fast: false
 
     steps:
@@ -388,6 +394,7 @@ jobs:
       run: pip install *.whl
 
     - name: Install test dependencies
+      if: ${{ matrix.type != 'doctest' }}
       run: pip install -r test/requirements.txt
 
     - uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
@@ -400,6 +407,7 @@ jobs:
       run: docker run -d --name aerospike -p 3000-3002:3000-3002 -e DEFAULT_TTL=2592000 ${{ env.REGISTRY_NAME }}/aerospike/aerospike-server:${{ env.SERVER_TAG }}
 
     - name: Create config.conf
+      if: ${{ matrix.type != 'doctest' }}
       run: cp config.conf.template config.conf
       working-directory: test
 
@@ -408,9 +416,22 @@ jobs:
         container-name: aerospike
 
     - name: Run tests
+      if: ${{ matrix.type != 'doctest' }}
       run: python -m pytest ./new_tests -vv -W error::pytest.PytestUnraisableExceptionWarning
       working-directory: test
 
+    - name: Install test dependencies
+      if: ${{ matrix.type == 'doctest' }}
+      run: pip install -r doc/requirements.txt
+
+    - if: ${{ matrix.type == 'doctest' }}
+      name: Run doctest
+      run: sphinx-build -b doctest . doctest
+      working-directory: doc
+
+    - if: ${{ !cancelled() }}
+      run: docker logs aerospike
+
   test-ee:
     runs-on: ubuntu-22.04
     needs: build

aerospike_helpers/__init__.py

@@ -20,8 +20,23 @@ class HyperLogLog(bytes):
 
     The constructor takes in any argument that the :class:`bytes` constructor takes in.
 
-    >>> h = HyperLogLog([1, 2, 3])
-    >>> client.put(key, {"hyperloglog": h})
+    .. testcode::
+
+        from aerospike_helpers import HyperLogLog
+        import aerospike
+
+        h = HyperLogLog([1, 2, 3])
+
+        client = aerospike.client({'hosts': [('localhost', 3000)]})
+        key = ("test", "demo", 1)
+        client.put(key, {"hyperloglog": h})
+
+        _, _, bins = client.get(key)
+        print(bins["hyperloglog"])
+
+    .. testoutput::
+
+        HyperLogLog(...)
     """
     def __new__(cls, o) -> "HyperLogLog":
         return super().__new__(cls, o)

aerospike_helpers/batch/records.py

@@ -81,11 +81,13 @@ def __init__(
         self, key: tuple, ops: "TypeOps", meta: Optional[dict] = None, policy: "TypeBatchPolicyWrite" = None
     ) -> None:
         """
-        Example::
+        Example:
+
+        .. testcode::
 
             # Create a batch Write to increment bin "a" by 10 and read the result from the record.
             import aerospike
-            import aerospike_helpers.operations as op
+            from aerospike_helpers.operations import operations as op
             from aerospike_helpers.batch.records import Write
 
             bin_name = "a"
@@ -140,11 +142,13 @@ def __init__(
         policy: "TypeBatchPolicyRead" = None,
     ) -> None:
         """
-        Example::
+        Example:
+
+        .. testcode::
 
             # Create a batch Read to read bin "a" from the record.
             import aerospike
-            import aerospike_helpers.operations as op
+            from aerospike_helpers.operations import operations as op
             from aerospike_helpers.batch.records import Read
 
             bin_name = "a"
@@ -192,12 +196,15 @@ def __init__(
         self, key: tuple, module: str, function: str, args: "TypeUDFArgs", policy: "TypeBatchPolicyApply" = None
     ) -> None:
         """
-        Example::
+        Example:
+
+        .. testcode::
 
             # Create a batch Apply to apply UDF "test_func" to bin "a" from the record.
             # Assume that "test_func" takes a bin name string as an argument.
             # Assume the appropriate UDF module has already been registered.
             import aerospike_helpers.operations as op
+            from aerospike_helpers.batch.records import Apply
 
 
             module = "my_lua"
@@ -240,7 +247,9 @@ class Remove(BatchRecord):
 
     def __init__(self, key: tuple, policy: "TypeBatchPolicyRemove" = None) -> None:
         """
-        Example::
+        Example:
+
+        .. testcode::
 
             # Create a batch Remove to remove the record.
             import aerospike_helpers.operations as op
@@ -251,7 +260,7 @@ def __init__(self, key: tuple, policy: "TypeBatchPolicyRemove" = None) -> None:
             user_key = 1
             key = (namespace, set, user_key)
 
-            br = Remove(key, ops)
+            br = Remove(key)
         """
         super().__init__(key)
         self._type = _Types.REMOVE
@@ -278,7 +287,9 @@ class BatchRecords:
 
     def __init__(self, batch_records: Optional[TypeBatchRecordList] = None) -> None:
         """
-        Example::
+        Example:
+
+        .. testcode::
 
             import aerospike
             import aerospike_helpers.operations.operations as op
@@ -328,12 +339,15 @@ def __init__(self, batch_records: Optional[TypeBatchRecordList] = None) -> None:
             for br in brs.batch_records:
                 print(br.result)
                 print(br.record)
-            # 0
-            # (('test', 'demo', 1, bytearray(b'...')), {'ttl': 4294967295, 'gen': 0}, {})
-            # 0
-            # (('test', 'demo', 2, bytearray(b'...')), {'ttl': 2592000, 'gen': 4}, {'id': 100})
-            # 0
-            # (('test', 'demo', 3, bytearray(b'...')), {'ttl': 2592000, 'gen': 3}, {'id': 1})
+
+        .. testoutput::
+
+            0
+            (('test', 'demo', 1, bytearray(b'...')), {...}, {})
+            0
+            (('test', 'demo', 2, bytearray(b'...')), {...}, {'id': 100})
+            0
+            (('test', 'demo', 3, bytearray(b'...')), {...}, {'id': 1})
         """
 
         if batch_records is None:

aerospike_helpers/cdt_ctx.py

@@ -17,7 +17,9 @@
 Helper functions to generate complex data type context (cdt_ctx) objects for use with operations on nested CDTs (list,
 map, etc).
 
-Example::
+Example:
+
+.. testcode::
 
     import aerospike
     from aerospike import exception as ex
@@ -51,7 +53,6 @@
 
     _, _, result = client.operate(key, ops)
     print(result)
-    # {'users': 200}
 
     # Example 2: add a new person and get their rating of Facebook
     cindy = {
@@ -76,11 +77,11 @@
 
     _, _, result = client.operate(key, ops)
     print(result)
-    # {'users': 4}
 
     # Example 3: create a CDT secondary index from a base64 encoded _cdt_ctx with info command
     policy = {}
 
+    ctx_list_index = [cdt_ctx.cdt_ctx_list_index(0)]
     bs_b4_cdt = client.get_cdtctx_base64(ctx_list_index)
 
     r = []
@@ -101,6 +102,11 @@
     client.remove(key)
     client.close()
 
+.. testoutput::
+
+    {'users': 200}
+    {'users': 4}
+
 .. _path_expressions_contexts:
 
 Path Expressions Contexts

aerospike_helpers/expressions/arithmetic.py

@@ -53,7 +53,10 @@ def __init__(self, *args: "TypeNumber"):
 
         :return: (integer or float value).
 
-        Example::
+        Example:
+
+        .. testcode::
+
 
             # Integer bin "a" + "b" == 11
             expr = exp.Eq(exp.Add(exp.IntBin("a"), exp.IntBin("b")), 11).compile()
@@ -86,7 +89,9 @@ def __init__(self, *args: "TypeNumber"):
 
         :return: (integer or float value)
 
-        Example::
+        Example:
+
+        .. testcode::
 
             # Integer bin "a" - "b" == 11
             expr = exp.Eq(exp.Sub(exp.IntBin("a"), exp.IntBin("b")), 11).compile()
@@ -117,7 +122,9 @@ def __init__(self, *args: "TypeNumber"):
 
         :return: (integer or float value)
 
-        Example::
+        Example:
+
+        .. testcode::
 
             # Integer bin "a" * "b" >= 11
             expr = exp.GE(exp.Mul(exp.IntBin("a"), exp.IntBin("b")), 11).compile()
@@ -150,7 +157,9 @@ def __init__(self, *args: "TypeNumber"):
 
         :return: (integer or float value)
 
-        Example::
+        Example:
+
+        .. testcode::
 
             # Integer bin "a" / "b" / "c" >= 11
             expr = exp.GE(exp.Div(exp.IntBin("a"), exp.IntBin("b"), exp.IntBin("c")), 11).compile()
@@ -184,7 +193,9 @@ def __init__(self, base: "TypeFloat", exponent: "TypeFloat"):
 
         :return: (float value)
 
-        Example::
+        Example:
+
+        .. testcode::
 
             # Float bin "a" ** 2.0 == 16.0
             expr = exp.Eq(exp.Pow(exp.FloatBin("a"), 2.0), 16.0).compile()
@@ -212,7 +223,9 @@ def __init__(self, num: "TypeFloat", base: "TypeFloat"):
 
         :return: (float value)
 
-        Example::
+        Example:
+
+        .. testcode::
 
             # For float bin "a", log("a", 2.0) == 16.0
             expr = exp.Eq(exp.Log(exp.FloatBin("a"), 2.0), 16.0).compile()
@@ -240,7 +253,9 @@ def __init__(self, numerator: "TypeInteger", denominator: "TypeInteger"):
 
         :return: (integer value)
 
-        Example::
+        Example:
+
+        .. testcode::
 
             # For int bin "a" % 10 == 0
             expr = exp.Eq(exp.Mod(exp.IntBin("a"), 10), 0).compile()
@@ -270,7 +285,9 @@ def __init__(self, value: "TypeNumber"):
 
         :return: (number value)
 
-        Example::
+        Example:
+
+        .. testcode::
 
             # For int bin "a", abs("a") == 1
             expr = exp.Eq(exp.Abs(exp.IntBin("a")), 1).compile()
@@ -300,7 +317,9 @@ def __init__(self, value: "TypeFloat"):
 
         :return: (float value)
 
-        Example::
+        Example:
+
+        .. testcode::
 
             # Floor(2.25) == 2.0
             expr = exp.Eq(exp.Floor(2.25), 2.0).compile()
@@ -331,7 +350,9 @@ def __init__(self, value: "TypeFloat"):
 
         :return: (float value)
 
-        Example::
+        Example:
+
+        .. testcode::
 
             # Ceil(2.25) == 3.0
             expr = exp.Eq(exp.Ceil(2.25), 3.0).compile()
@@ -357,7 +378,9 @@ def __init__(self, value: "TypeFloat"):
 
         :return: (integer value)
 
-        Example::
+        Example:
+
+        .. testcode::
 
             #For float bin "a", int(exp.FloatBin("a")) == 2
             expr = exp.Eq(exp.ToInt(exp.FloatBin("a")), 2).compile()
@@ -379,7 +402,9 @@ def __init__(self, value: "TypeInteger"):
 
         :return: (float value)
 
-        Example::
+        Example:
+
+        .. testcode::
 
             #For int bin "a", float(exp.IntBin("a")) == 2
             expr = exp.Eq(exp.ToFloat(exp.IntBin("a")), 2).compile()
@@ -404,7 +429,9 @@ def __init__(self, *args: "TypeNumber"):
 
         :return: (integer or float value).
 
-        Example::
+        Example:
+
+        .. testcode::
 
             # for integer bins a, b, c, min(a, b, c) > 0
             expr = exp.GT(exp.Min(exp.IntBin("a"), exp.IntBin("b"), exp.IntBin("c")), 0).compile()
@@ -428,7 +455,9 @@ def __init__(self, *args: "TypeNumber"):
 
         :return: (integer or float value).
 
-        Example::
+        Example:
+
+        .. testcode::
 
             # for integer bins a, b, c, max(a, b, c) > 100
             expr = exp.GT(exp.Max(exp.IntBin("a"), exp.IntBin("b"), exp.IntBin("c")), 100).compile()