From a9dbc3752fc9cf449ae56ece08675384047235b5 Mon Sep 17 00:00:00 2001
From: Mauro Silberberg <maurosilber@gmail.com>
Date: Fri, 27 Dec 2024 13:17:14 -0300
Subject: [PATCH] Add type stubs for python code

https://pyo3.rs/v0.23.3/python-typing-hints
---
 pyproject.toml         |  1 +
 python/rebop/py.typed  |  0
 python/rebop/rebop.pyi | 38 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 39 insertions(+)
 create mode 100644 python/rebop/py.typed
 create mode 100644 python/rebop/rebop.pyi

diff --git a/pyproject.toml b/pyproject.toml
index 1adc511..3e48ee7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -30,6 +30,7 @@ ignore = [
   "COM812",  # Incompatible with ruff-format
   "ISC001",  # Incompatible with ruff-format
   "RET504",  # Unnecessary asignment before return
+  "PYI021",  # Docstrings should not be included in stubs
 ]
 
 [tool.ruff.lint.per-file-ignores]
diff --git a/python/rebop/py.typed b/python/rebop/py.typed
new file mode 100644
index 0000000..e69de29
diff --git a/python/rebop/rebop.pyi b/python/rebop/rebop.pyi
new file mode 100644
index 0000000..408be59
--- /dev/null
+++ b/python/rebop/rebop.pyi
@@ -0,0 +1,38 @@
+import xarray
+
+class Gillespie:
+    """Reaction system composed of species and reactions."""
+
+    def add_reaction(
+        self,
+        /,
+        rate: float,
+        reactants: list[str],
+        products: list[str],
+        reverse_rate: float | None = None,
+    ) -> None:
+        """Add a Law of Mass Action reaction to the system.
+
+        The forward reaction rate is `rate`, while `reactants` and `products` are
+        lists of respectively reactant names and product names.
+        Add the reverse reaction with the rate `reverse_rate` if it is not `None`.
+        """
+
+    def nb_reactions(self, /) -> int:
+        """Number of reactions currently in the system."""
+
+    def nb_species(self, /) -> int:
+        """Number of species currently in the system."""
+
+    def run(
+        self,
+        init: dict[str, int],
+        tmax: float,
+        nb_steps: int,
+        seed: int | None = None,
+    ) -> xarray.Dataset:
+        """Run the system until `tmax` with `nb_steps` steps.
+
+        The initial configuration is specified in the dictionary `init`.
+        Returns an xarray Dataset.
+        """