Use pyo3-stub-gen to support IDE type hints

Cargo.toml

@@ -36,6 +36,8 @@ tabled = { version = "0.16.0", optional = true }
 openssl = { version = "0.10", features = ["vendored"], optional = true }
 web-time = { version = "1.0.0", optional = true }
 snafu = { version = "0.8.2", default-features = false }
+pyo3-stub-gen = { version = "0.6.0", default-features = false }
+pyo3-stub-gen-derive = "0.6.0"
 
 [features]
 default = ["std"]

hifitime.pyi

@@ -0,0 +1,81 @@
+# This file is automatically generated by pyo3_stub_gen
+# ruff: noqa: E501, F401
+
+import typing
+from enum import Enum, auto
+
+class DurationError:
+    def __new__(cls,* _args,* * _kwargs): ...
+    ...
+
+class Epoch:
+    r"""
+    Defines a nanosecond-precision Epoch.
+
+    Refer to the appropriate functions for initializing this Epoch from different time scales or representations.
+    """
+    ...
+
+class HifitimeError:
+    def __new__(cls,* _args,* * _kwargs): ...
+    ...
+
+class LatestLeapSeconds:
+    r"""
+    List of leap seconds from https://www.ietf.org/timezones/data/leap-seconds.list .
+    This list corresponds the number of seconds in TAI to the UTC offset and to whether it was an announced leap second or not.
+    The unannoucned leap seconds come from dat.c in the SOFA library.
+    """
+    def __new__(cls,): ...
+    def __repr__(self) -> str:
+        ...
+
+
+class LeapSecond:
+    r"""
+    A structure representing a leap second
+    """
+    ...
+
+class LeapSecondsFile:
+    r"""
+    A leap second provider that uses an IERS formatted leap seconds file.
+    """
+    def __new__(cls,path:str): ...
+    def __repr__(self) -> str:
+        ...
+
+
+class ParsingError:
+    def __new__(cls,* _args,* * _kwargs): ...
+    ...
+
+class TimeSeries:
+    r"""
+    An iterator of a sequence of evenly spaced Epochs.
+    """
+    ...
+
+class Ut1Provider:
+    r"""
+    A structure storing all of the TAI-UT1 data
+    """
+    def __new__(cls,): ...
+    def __repr__(self) -> str:
+        ...
+
+
+class TimeScale(Enum):
+    r"""
+    Enum of the different time systems available
+    """
+    TAI = auto()
+    TT = auto()
+    ET = auto()
+    TDB = auto()
+    UTC = auto()
+    GPST = auto()
+    GST = auto()
+    BDT = auto()
+    QZSST = auto()
+

src/bin/stub_gen.rs

@@ -0,0 +1,13 @@
+use pyo3_stub_gen::Result;
+
+#[cfg(feature = "python")]
+fn main() -> Result<()> {
+    let stub = hifitime::python::stub_info()?;
+    stub.generate()?;
+    Ok(())
+}
+
+#[cfg(not(feature = "python"))]
+fn main() -> Result<()> {
+    Ok(())
+}

src/epoch/leap_seconds.rs

@@ -11,6 +11,9 @@
 #[cfg(feature = "python")]
 use pyo3::prelude::*;
 
+#[cfg(feature = "python")]
+use pyo3_stub_gen::derive::*;
+
 #[cfg(feature = "std")]
 pub use super::leap_seconds_file::LeapSecondsFile;
 
@@ -21,6 +24,7 @@ pub trait LeapSecondProvider: DoubleEndedIterator<Item = LeapSecond> + Index<usi
 /// A structure representing a leap second
 #[cfg_attr(kani, derive(kani::Arbitrary))]
 #[repr(C)]
+#[cfg_attr(feature = "python", gen_stub_pyclass)]
 #[cfg_attr(feature = "python", pyclass)]
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub struct LeapSecond {
@@ -90,6 +94,7 @@ const LATEST_LEAP_SECONDS: [LeapSecond; 42] = [
 /// List of leap seconds from https://www.ietf.org/timezones/data/leap-seconds.list .
 /// This list corresponds the number of seconds in TAI to the UTC offset and to whether it was an announced leap second or not.
 /// The unannoucned leap seconds come from dat.c in the SOFA library.
+#[cfg_attr(feature = "python", gen_stub_pyclass)]
 #[cfg_attr(feature = "python", pyclass)]
 #[cfg_attr(kani, derive(kani::Arbitrary))]
 #[derive(Clone, Debug)]
@@ -99,6 +104,7 @@ pub struct LatestLeapSeconds {
 }
 
 #[cfg(feature = "python")]
+#[cfg_attr(feature = "python", gen_stub_pymethods)]
 #[cfg_attr(feature = "python", pymethods)]
 impl LatestLeapSeconds {
     #[new]

src/epoch/leap_seconds_file.rs

@@ -11,6 +11,9 @@
 #[cfg(feature = "python")]
 use pyo3::prelude::*;
 
+#[cfg(feature = "python")]
+use pyo3_stub_gen::derive::*;
+
 use std::{fs::File, io::Read, path::Path};
 
 use core::ops::Index;
@@ -21,6 +24,7 @@ use crate::{
 };
 
 #[repr(C)]
+#[cfg_attr(feature = "python", gen_stub_pyclass)]
 #[cfg_attr(feature = "python", pyclass)]
 #[derive(Clone, Debug, Default)]
 /// A leap second provider that uses an IERS formatted leap seconds file.
@@ -100,6 +104,7 @@ impl LeapSecondsFile {
 }
 
 #[cfg(feature = "python")]
+#[cfg_attr(feature = "python", gen_stub_pymethods)]
 #[cfg_attr(feature = "python", pymethods)]
 impl LeapSecondsFile {
     #[new]

src/epoch/mod.rs

@@ -53,6 +53,9 @@ mod python;
 #[cfg(feature = "python")]
 use pyo3::prelude::*;
 
+#[cfg(feature = "python")]
+use pyo3_stub_gen::derive::*;
+
 #[cfg(not(kani))]
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
@@ -79,6 +82,7 @@ pub const NAIF_K: f64 = 1.657e-3;
 #[cfg_attr(kani, derive(kani::Arbitrary))]
 #[derive(Copy, Clone, Default, Eq)]
 #[repr(C)]
+#[cfg_attr(feature = "python", gen_stub_pyclass)]
 #[cfg_attr(feature = "python", pyclass)]
 #[cfg_attr(feature = "python", pyo3(module = "hifitime"))]
 pub struct Epoch {

src/epoch/ut1.rs

@@ -11,6 +11,9 @@
 #[cfg(feature = "python")]
 use pyo3::prelude::*;
 
+#[cfg(feature = "python")]
+use pyo3_stub_gen::derive::*;
+
 use reqwest::{blocking::get, StatusCode};
 
 use tabled::settings::Style;
@@ -72,6 +75,7 @@ pub struct DeltaTaiUt1 {
 }
 
 #[repr(C)]
+#[cfg_attr(feature = "python", gen_stub_pyclass)]
 #[cfg_attr(feature = "python", pyclass)]
 #[derive(Clone, Debug, Default)]
 /// A structure storing all of the TAI-UT1 data
@@ -187,6 +191,7 @@ impl Ut1Provider {
 }
 
 #[cfg(feature = "python")]
+#[cfg_attr(feature = "python", gen_stub_pymethods)]
 #[cfg_attr(feature = "python", pymethods)]
 impl Ut1Provider {
     #[new]

src/python.rs

@@ -17,6 +17,7 @@ use pyo3::{
 use crate::leap_seconds::{LatestLeapSeconds, LeapSecondsFile};
 use crate::prelude::*;
 use crate::ut1::Ut1Provider;
+use pyo3_stub_gen::{define_stub_info_gatherer, derive::*};
 
 // Keep the module at the top
 #[pymodule]
@@ -35,10 +36,12 @@ fn hifitime(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
     Ok(())
 }
 
+#[gen_stub_pyclass]
 #[pyclass]
 #[pyo3(name = "HifitimeError", extends = PyException)]
 pub struct PyHifitimeError {}
 
+#[gen_stub_pymethods]
 #[pymethods]
 impl PyHifitimeError {
     #[new]
@@ -48,10 +51,12 @@ impl PyHifitimeError {
     }
 }
 
+#[gen_stub_pyclass]
 #[pyclass]
 #[pyo3(name = "ParsingError", extends = PyException)]
 pub struct PyParsingError {}
 
+#[gen_stub_pymethods]
 #[pymethods]
 impl PyParsingError {
     #[new]
@@ -61,10 +66,12 @@ impl PyParsingError {
     }
 }
 
+#[gen_stub_pyclass]
 #[pyclass]
 #[pyo3(name = "DurationError", extends = PyException)]
 pub struct PyDurationError {}
 
+#[gen_stub_pymethods]
 #[pymethods]
 impl PyDurationError {
     #[new]
@@ -92,3 +99,5 @@ impl From<DurationError> for PyErr {
         PyException::new_err(err.to_string())
     }
 }
+
+define_stub_info_gatherer!(stub_info);

src/timescale/mod.rs

@@ -11,6 +11,9 @@
 #[cfg(feature = "python")]
 use pyo3::prelude::*;
 
+#[cfg(feature = "python")]
+use pyo3_stub_gen::derive::*;
+
 #[cfg(kani)]
 mod kani;
 
@@ -81,6 +84,7 @@ pub(crate) const HIFITIME_REF_YEAR: i32 = 1900;
 
 /// Enum of the different time systems available
 #[non_exhaustive]
+#[cfg_attr(feature = "python", gen_stub_pyclass_enum)]
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[cfg_attr(feature = "python", pyclass(eq, eq_int))]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
@@ -171,6 +175,7 @@ impl TimeScale {
     }
 }
 
+#[cfg_attr(feature = "python", gen_stub_pymethods)]
 #[cfg_attr(feature = "python", pymethods)]
 impl TimeScale {
     /// Returns true if self takes leap seconds into account

src/timeseries.rs

@@ -19,6 +19,9 @@ use num_traits::Float;
 #[cfg(feature = "python")]
 use pyo3::prelude::*;
 
+#[cfg(feature = "python")]
+use pyo3_stub_gen::derive::*;
+
 /*
 
 NOTE: This is taken from itertools: https://docs.rs/itertools-num/0.1.3/src/itertools_num/linspace.rs.html#78-93 .
@@ -28,6 +31,7 @@ NOTE: This is taken from itertools: https://docs.rs/itertools-num/0.1.3/src/iter
 /// An iterator of a sequence of evenly spaced Epochs.
 #[cfg_attr(kani, derive(kani::Arbitrary))]
 #[derive(Clone, Debug, PartialEq, Eq)]
+#[cfg_attr(feature = "python", gen_stub_pyclass)]
 #[cfg_attr(feature = "python", pyclass)]
 #[cfg_attr(feature = "python", pyo3(module = "hifitime"))]
 pub struct TimeSeries {