QDB-16709 - Add stubgen support

[rodp63]

Worked with pybind11-stubgen as base tool, which produced more accurate results than stubgen from mypy.

Summary of Changes

• Added .pyi stub files for all exposed C++ modules.
• Classes that require a qdb::handle in their constructors can no longer be directly instantiated. This is enforced via the following binding:

  .def(py::init([](py::args, py::kwargs) {
    throw qdb::direct_instantiation_exception{};
    return nullptr;
  }))

  For example:

  t = quasardb.Table("my_table")
  # DirectInstantiationError: Direct instantiation is not allowed, use 'conn.table(...)' instead.

• These restricted classes are excluded from the top-level quasardb stub module to prevent direct instantiation. They still can be imported at runtime, but no type hints will be shown.
• The method conn.find() now returns the result directly, aligning its behavior with conn.query() for consistency.

[Copilot]

Pull Request Overview

Adds stub generation support by providing .pyi files, enforcing direct instantiation guards in C++ bindings, and aligning the return value of cluster.find with cluster.query.

• Introduces a new stub module (.pyi) for the QuasarDB Python API.
• Replaces default constructors on protected classes with lambdas that throw DirectInstantiationError.
• Updates cluster.find to return a std::vector<std::string> directly and adjusts the binding.

Reviewed Changes

Copilot reviewed 53 out of 53 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
quasardb/quasardb/__init__.pyi	New stub file defining the public Python API
properties.hpp, perf.hpp, options.hpp, …	Modified bindings to throw DirectInstantiationError in py::init lambdas
cluster.hpp / cluster.cpp	Changed find to return a vector<string> and updated its binding
module.cpp	Initialized never_expires via Python’s datetime.fromtimestamp
dev-requirements.txt	Added mypy and pybind11-stubgen in development requirements

Comments suppressed due to low confidence (3)

quasardb/cluster.hpp:340

• [nitpick] The variable name o is vague; consider renaming it to something more descriptive like query_obj or finder.

auto o = std::make_shared<qdb::find_query>(_handle, query_string);

quasardb/cluster.hpp:335

• Add or update unit tests for the new find implementation that directly returns std::vector<std::string> to verify correct behavior.

qdb::find_query find(const std::string & query_string)

quasardb/quasardb/init.pyi:83

• The metrics symbol is included in __all__ but never imported; either add its import (e.g. from ._perf import metrics) or remove it from __all__.

"metrics",