feat: Accept None as column values in Buffer.row() API. (#6)

Author: amunra

DEV_NOTES.rst

@@ -28,7 +28,7 @@ Install your local Python3 environment **venv**
     venv/bin/python install -r dev_requirements.txt
 
     # or simply:
-    python3 proj.py venv
+    ./proj venv
 
     # either of the ^ ^ should be followed by:
     source venv/bin/activate
@@ -80,15 +80,15 @@ No wheels are made.
 
 .. code-block:: bash
 
-    python3 proj.py build
+    ./proj build
 
 
 Cleaning
 --------
 
 .. code-block:: bash
 
-    python3 proj.py clean
+    ./proj clean
 
 
 Packaging Locally
@@ -99,8 +99,8 @@ MacOS Apple Silicon, run:
 
 .. code-block:: bash
 
-    python3 proj.py sdist   # source distribution
-    python3 proj.py cibuildwheel # the order of these two lines does not matter
+    ./proj sdist   # source distribution
+    ./proj cibuildwheel # the order of these two lines does not matter
 
 This will end up putting everything in the ``dist/`` directory.
 
@@ -239,4 +239,4 @@ In ``pyproject.toml``, add the following to the ``[tool.cibuildwheel]`` section:
     yum -y install valgrind
     """
 
-Note the ``gdb/commands.txt`` file. Review it and change it to fit your needs.
+Note the ``gdb/commands.txt`` file. Review it and change it to fit your needs.

proj

@@ -0,0 +1,2 @@
+#!/bin/sh
+python3 proj.py "$@"

proj.ps1

@@ -0,0 +1 @@
+python3 proj.py $args

src/questdb/ingress.pyx

@@ -635,14 +635,11 @@ cdef class Buffer:
         self._set_marker()
         try:
             self._table(table_name)
-            if not (symbols or columns):
-                raise IngressError(
-                    IngressErrorCode.InvalidApiCall,
-                    'Must specify at least one symbol or column')
             if symbols is not None:
                 for name, value in symbols.items():
-                    self._symbol(name, value)
-                    wrote_fields = True
+                    if value is not None:
+                        self._symbol(name, value)
+                        wrote_fields = True
             if columns is not None:
                 for name, value in columns.items():
                     if value is not None:
@@ -663,7 +660,7 @@ cdef class Buffer:
             self,
             table_name: str,
             *,
-            symbols: Optional[Dict[str, str]]=None,
+            symbols: Optional[Dict[str, Optional[str]]]=None,
             columns: Optional[Dict[
                 str,
                 Union[None, bool, int, float, str, TimestampMicros, datetime]]
@@ -672,14 +669,12 @@ cdef class Buffer:
         """
         Add a single row (line) to the buffer.
 
-        At least one ``symbols`` or ``columns`` must be specified.
-
         .. code-block:: python
 
             # All fields specified.
             buffer.row(
                 'table_name',
-                symbols={'sym1': 'abc', 'sym2': 'def'},
+                symbols={'sym1': 'abc', 'sym2': 'def', 'sym3': None},
                 columns={
                     'col1': True,
                     'col2': 123,
@@ -741,12 +736,16 @@ cdef class Buffer:
 
         :param table_name: The name of the table to which the row belongs.
         :param symbols: A dictionary of symbol column names to ``str`` values.
+            As a convenience, you can also pass a ``None`` value which will
+            have the same effect as skipping the key: If the column already
+            existed, it will be recorded as ``NULL``, otherwise it will not be
+            created.
         :param columns: A dictionary of column names to ``bool``, ``int``,
             ``float``, ``str``, ``TimestampMicros`` or ``datetime`` values.
-            As a convenience, you can also pass a ``None`` value, however - due
-            to ILP protocol limitations - this will skip the column rather
-            necessarily writing a ``NULL`` value, so if the column did not exist
-            yet it will not be created.
+            As a convenience, you can also pass a ``None`` value which will
+            have the same effect as skipping the key: If the column already
+            existed, it will be recorded as ``NULL``, otherwise it will not be
+            created.
         :param at: The timestamp of the row. If ``None``, timestamp is assigned
             by the server. If ``datetime``, the timestamp is converted to
             nanoseconds. A nanosecond unix epoch timestamp can be passed

test/test.py

@@ -75,6 +75,18 @@ def test_column(self):
             'col5="val",col6=12345t,col7=7200000000t\n')
         self.assertEqual(str(buf), exp)
 
+    def test_none_symbol(self):
+        buf = qi.Buffer()
+        buf.row('tbl1', symbols={'sym1': 'val1', 'sym2': None})
+        exp = 'tbl1,sym1=val1\n'
+        self.assertEqual(str(buf), exp)
+        self.assertEqual(len(buf), len(exp))
+
+        # No fields to write, no fields written, therefore a no-op.
+        buf.row('tbl1', symbols={'sym1': None, 'sym2': None})
+        self.assertEqual(str(buf), exp)
+        self.assertEqual(len(buf), len(exp))
+
     def test_none_column(self):
         buf = qi.Buffer()
         buf.row('tbl1', columns={'col1': 1})
@@ -87,6 +99,11 @@ def test_none_column(self):
         self.assertEqual(str(buf), exp)
         self.assertEqual(len(buf), len(exp))
 
+    def test_no_symbol_or_col_args(self):
+        buf = qi.Buffer()
+        buf.row('table_name')
+        self.assertEqual(str(buf), '')
+
     def test_unicode(self):
         buf = qi.Buffer()
         buf.row('tbl1', symbols={'questdb1': '❤️'}, columns={'questdb2': '❤️'})