QDB-16709 - Add stubgen support

.github/workflows/lint.yml

@@ -1,16 +1,18 @@
-name: Lint
+name: Format check
 
 on:
   push:
     branches:
       - master
     paths:
       - '**.py'
+      - '**.pyi'
   pull_request:
     branches:
       - master
     paths:
       - '**.py'
+      - '**.pyi'
 
 jobs:
   lint:
@@ -28,15 +30,30 @@ jobs:
         run: |
           pip install -r scripts/github_actions/requirements.txt
 
-      - name: Run black
-        id: run_black
+      - name: Run black on Python files
         run: |
           black --check --verbose .
 
-      # - name: Run post-lint actions
-      #   if: ${{ !cancelled() }}
-      #   env:
-      #     SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
-      #     SLACK_BOT_CHANNEL: ${{ vars.SLACK_BOT_CHANNEL }}
-      #   run: |
-      #     python scripts/github_actions/post_lint.py ${{ steps.run_black.outcome }}
+      - name: Run black on stub files
+        run: |
+          black --include '\.pyi$' --check --verbose .
+
+  # typing:
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - name: Check out code
+  #       uses: actions/checkout@v4
+
+  #     - name: Setup Python version
+  #       uses: actions/setup-python@v5
+  #       with:
+  #         python-version: '3.13'
+
+  #     - name: Install dependencies
+  #       run: |
+  #         pip install -r scripts/github_actions/requirements.txt
+  #         pip install -r dev-requirements.txt
+
+  #     - name: Run mypy
+  #       run: |
+  #         mypy --check quasardb

.gitignore

@@ -138,6 +138,9 @@ venv
 # PyCharm
 .idea
 
+# MacOS
+.DS_Store
+
 # Test specific
 cluster_private.key
 cluster_public.key

dev-requirements.txt

@@ -3,7 +3,7 @@
 # FreeBSD), and there are some conflicting requirements. For example, Numpy
 # doesn't have any version that works on both Python 3.6 and Python 3.10.
 
-numpy ~= 1.19.5; python_version <= '3.7'
+# numpy ~= 1.19.5; python_version <= '3.7'
 numpy ~= 1.20.3; python_version == '3.8'
 numpy ~= 1.20.3; python_version == '3.9'
 numpy >= 2.0.1;  python_version > '3.9'
@@ -36,4 +36,8 @@ teamcity-messages == 1.29
 setuptools-git == 1.2
 
 # Linting
-black
+black==24.10.0
+
+# Stubs
+mypy
+pybind11-stubgen

pyproject.toml

@@ -24,3 +24,6 @@ addopts = ["-s", "-x"]
 xfail_strict = true
 filterwarnings = []
 testpaths = ["tests"]
+
+# [tool.mypy]
+# python_version = "3.9"

quasardb/__init__.py

@@ -36,7 +36,10 @@
 """
 
 
-def generic_error_msg(msg, e=None):
+from typing import List, Optional
+
+
+def generic_error_msg(msg: List[str], e: Optional[BaseException] = None) -> str:
     msg_str = "\n".join(msg)
 
     if e is None:
@@ -47,7 +50,7 @@ def generic_error_msg(msg, e=None):
 
 **************************************************************************
 """.format(
-            msg_str, type(e), str(e)
+            msg_str
         )
     else:
         return """
@@ -68,7 +71,7 @@ def generic_error_msg(msg, e=None):
         )
 
 
-def link_error_msg(e):
+def link_error_msg(e: BaseException) -> str:
     msg = [
         "QuasarDB was unable to find all expected symbols in the compiled library.",
         "This is usually caused by running an incorrect version of the QuasarDB C",
@@ -82,7 +85,7 @@ def link_error_msg(e):
     return generic_error_msg(msg, e)
 
 
-def glibc_error_msg(e):
+def glibc_error_msg(e: BaseException) -> str:
     msg = [
         "QuasarDB was unable to find the expected GLIBC version on this machine.",
         "This is usually caused by compiling the Python API on a different machine "
@@ -99,7 +102,7 @@ def glibc_error_msg(e):
     return generic_error_msg(msg, e)
 
 
-def unknown_error_msg():
+def unknown_error_msg() -> str:
     msg = [
         "Unable to import quasardb module: unknown error. ",
         "",

quasardb/__init__.pyi

@@ -0,0 +1,72 @@
+"""
+
+.. module: quasardb
+    :platform: Unix, Windows
+    :synopsis: quasardb official Python API
+
+.. moduleauthor: quasardb SAS. All rights reserved
+"""
+
+from __future__ import annotations
+
+from quasardb.quasardb import (
+    AliasAlreadyExistsError,
+    AliasNotFoundError,
+    AsyncPipelineFullError,
+    BatchColumnInfo,
+    Cluster,
+    ColumnInfo,
+    ColumnType,
+    Error,
+    IncompatibleTypeError,
+    IndexedColumnInfo,
+    InputBufferTooSmallError,
+    InternalLocalError,
+    InvalidArgumentError,
+    InvalidDatetimeError,
+    InvalidHandleError,
+    InvalidQueryError,
+    Node,
+    NotImplementedError,
+    OutOfBoundsError,
+    RetryOptions,
+    TryAgainError,
+    UninitializedError,
+    WriterData,
+    WriterPushMode,
+    build,
+    metrics,
+    never_expires,
+    version,
+)
+
+__all__ = [
+    "AliasAlreadyExistsError",
+    "AliasNotFoundError",
+    "AsyncPipelineFullError",
+    "BatchColumnInfo",
+    "Cluster",
+    "ColumnInfo",
+    "ColumnType",
+    "Error",
+    "IncompatibleTypeError",
+    "IndexedColumnInfo",
+    "InputBufferTooSmallError",
+    "InternalLocalError",
+    "InvalidArgumentError",
+    "InvalidDatetimeError",
+    "InvalidHandleError",
+    "InvalidQueryError",
+    "Node",
+    "NotImplementedError",
+    "OutOfBoundsError",
+    "RetryOptions",
+    "TryAgainError",
+    "UninitializedError",
+    "WriterData",
+    "WriterPushMode",
+    "build",
+    "metrics",
+    "never_expires",
+    "version",
+]

quasardb/batch_column.hpp

@@ -67,14 +67,14 @@ static inline void register_batch_column(Module & m)
 {
     namespace py = pybind11;
 
-    py::class_<qdb::batch_column_info>{m, "BatchColumnInfo"}                                 //
-        .def(py::init<const std::string &, const std::string &, qdb_size_t>(),               //
-            py::arg("ts_name"),                                                              //
-            py::arg("col_name"),                                                             //
-            py::arg("size_hint") = 0)                                                        //
-        .def_readwrite("timeseries", &qdb::batch_column_info::timeseries)                    //
-        .def_readwrite("column", &qdb::batch_column_info::column)                            //
-        .def_readwrite("elements_count_hint", &qdb::batch_column_info::elements_count_hint); //
+    py::class_<qdb::batch_column_info>{m, "BatchColumnInfo"}
+        .def(py::init<const std::string &, const std::string &, qdb_size_t>(),
+            py::arg("ts_name"),
+            py::arg("col_name"),
+            py::arg("size_hint") = 0)
+        .def_readwrite("timeseries", &qdb::batch_column_info::timeseries)
+        .def_readwrite("column", &qdb::batch_column_info::column)
+        .def_readwrite("elements_count_hint", &qdb::batch_column_info::elements_count_hint);
 }
 
 } // namespace qdb

quasardb/batch_inserter.hpp

@@ -225,18 +225,21 @@ static inline void register_batch_inserter(Module & m)
 {
     namespace py = pybind11;
 
-    py::class_<qdb::batch_inserter>{m, "TimeSeriesBatch"}                         //
-        .def(py::init<qdb::handle_ptr, const std::vector<batch_column_info> &>()) //
+    py::class_<qdb::batch_inserter>{m, "TimeSeriesBatch"}
+	.def(py::init([](py::args, py::kwargs) {
+	    throw qdb::direct_instantiation_exception{"conn.ts_batch(...)"};
+	    return nullptr;
+        }))
         .def("start_row", &qdb::batch_inserter::start_row,
-            "Calling this function marks the beginning of processing a new row.") //
-        .def("set_blob", &qdb::batch_inserter::set_blob)                          //
-        .def("set_string", &qdb::batch_inserter::set_string)                      //
-        .def("set_double", &qdb::batch_inserter::set_double)                      //
-        .def("set_int64", &qdb::batch_inserter::set_int64)                        //
-        .def("set_timestamp", &qdb::batch_inserter::set_timestamp)                //
-        .def("push", &qdb::batch_inserter::push, "Regular batch push")            //
+            "Calling this function marks the beginning of processing a new row.")
+        .def("set_blob", &qdb::batch_inserter::set_blob)
+        .def("set_string", &qdb::batch_inserter::set_string)
+        .def("set_double", &qdb::batch_inserter::set_double)
+        .def("set_int64", &qdb::batch_inserter::set_int64)
+        .def("set_timestamp", &qdb::batch_inserter::set_timestamp)
+        .def("push", &qdb::batch_inserter::push, "Regular batch push")
         .def("push_async", &qdb::batch_inserter::push_async,
-            "Asynchronous batch push that buffers data inside the QuasarDB daemon") //
+            "Asynchronous batch push that buffers data inside the QuasarDB daemon")
         .def("push_fast", &qdb::batch_inserter::push_fast,
             "Fast, in-place batch push that is efficient when doing lots of small, incremental pushes.")
         .def("push_truncate", &qdb::batch_inserter::push_truncate,

quasardb/blob.hpp

@@ -133,18 +133,21 @@ static inline void register_blob(Module & m)
 {
     namespace py = pybind11;
 
-    py::class_<qdb::blob_entry, qdb::expirable_entry>(m, "Blob") //
-        .def(py::init<qdb::handle_ptr, std::string>())           //
-        .def("get", &qdb::blob_entry::get)                       //
-        .def("put", &qdb::blob_entry::put, py::arg("data"))      //
+    py::class_<qdb::blob_entry, qdb::expirable_entry>(m, "Blob")
+        .def(py::init([](py::args, py::kwargs) {
+	    throw qdb::direct_instantiation_exception{"conn.blob(...)"};
+	    return nullptr;
+        }))
+        .def("get", &qdb::blob_entry::get)
+        .def("put", &qdb::blob_entry::put, py::arg("data"))
         .def("update", &qdb::blob_entry::update, py::arg("data"),
-            py::arg("expiry") = std::chrono::system_clock::time_point{})     //
-        .def("remove_if", &qdb::blob_entry::remove_if, py::arg("comparand")) //
-        .def("get_and_remove", &qdb::blob_entry::get_and_remove)             //
-        .def("get_and_update", &qdb::blob_entry::get_and_update,             //
-            py::arg("data"))                                                 //
-        .def("compare_and_swap", &qdb::blob_entry::compare_and_swap,         //
-            py::arg("new_content"), py::arg("comparand"));                   //
+            py::arg("expiry") = std::chrono::system_clock::time_point{})
+        .def("remove_if", &qdb::blob_entry::remove_if, py::arg("comparand"))
+        .def("get_and_remove", &qdb::blob_entry::get_and_remove)
+        .def("get_and_update", &qdb::blob_entry::get_and_update,
+            py::arg("data"))
+        .def("compare_and_swap", &qdb::blob_entry::compare_and_swap,
+            py::arg("new_content"), py::arg("comparand"));
 }
 
 } // namespace qdb