Merge b4fd314 into 238feed

docs/documentation.rst

@@ -17,6 +17,14 @@ spiceypy.utils.support_types module
     :undoc-members:
     :show-inheritance:
 
+spiceypy.utils.callbacks module
+-----------------------------------
+
+.. automodule:: spiceypy.utils.callbacks
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 spiceypy.utils.libspice module
 ------------------------------
 

docs/environment.yml

@@ -6,5 +6,6 @@ channels:
 dependencies:
   - python=3
   - numpy
+  - sphinx==2.3.1
   - pip:
     - sphinx_autodoc_typehints

docs/requirements.txt

@@ -1,2 +1,3 @@
 numpy
-sphinx_autodoc_typehints
+sphinx_autodoc_typehints
+sphinx==2.3.1

spiceypy/spiceypy.py

@@ -29,6 +29,7 @@
 from . import config
 from .utils.callbacks import SpiceUDFUNS, SpiceUDFUNB
 from .utils.callbacks import (
+    UDFUNC,
     UDFUNS,
     UDFUNB,
     UDSTEP,
@@ -51,6 +52,7 @@
     Ellipse,
     Plane,
     SpiceCell,
+    SpiceCellPointer,
     SpiceDLADescr,
     SpiceDSKDescr,
     SpiceEKAttDsc,
@@ -244,7 +246,7 @@ def cell_bool(cell_size: int) -> SpiceCell:
     return stypes.SPICEBOOL_CELL(cell_size)
 
 
-def cell_time(cell_size):
+def cell_time(cell_size) -> SpiceCell:
     return stypes.SPICETIME_CELL(cell_size)
 
 
@@ -1366,7 +1368,7 @@ def ckw05(
     )
 
 
-def cleard():
+def cleard() -> NotImplementedError:
     raise NotImplementedError
 
 
@@ -6271,7 +6273,9 @@ def gfrepf() -> None:
 
 
 @spice_error_check
-def gfrepi(window: SpiceCell, begmss: str, endmss: str) -> None:
+def gfrepi(
+    window: Union[SpiceCell, SpiceCellPointer], begmss: str, endmss: str
+) -> None:
     """
     This entry point initializes a search progress report.
 
@@ -6284,7 +6288,7 @@ def gfrepi(window: SpiceCell, begmss: str, endmss: str) -> None:
     begmss = stypes.string_to_char_p(begmss)
     endmss = stypes.string_to_char_p(endmss)
     # don't do anything if we were given a pointer to a SpiceCell, like if we were in a callback
-    if not isinstance(window, ctypes.POINTER(stypes.SpiceCell)):
+    if not isinstance(window, SpiceCellPointer):
         assert isinstance(window, stypes.SpiceCell)
         assert window.is_double()
         window = ctypes.byref(window)
@@ -6767,7 +6771,9 @@ def gftfov(
 
 
 @spice_error_check
-def gfudb(udfuns, udfunb, step, cnfine, result):
+def gfudb(
+    udfuns: UDFUNS, udfunb: UDFUNB, step: float, cnfine: SpiceCell, result: SpiceCell
+):
     """
     Perform a GF search on a user defined boolean quantity.
 
@@ -6785,7 +6791,17 @@ def gfudb(udfuns, udfunb, step, cnfine, result):
 
 
 @spice_error_check
-def gfuds(udfuns, udqdec, relate, refval, adjust, step, nintvls, cnfine, result):
+def gfuds(
+    udfuns: UDFUNS,
+    udqdec: UDFUNB,
+    relate: str,
+    refval: float,
+    adjust: float,
+    step: float,
+    nintvls: int,
+    cnfine: SpiceCell,
+    result: SpiceCell,
+) -> SpiceCell:
     """
     Perform a GF search on a user defined scalar quantity.
 
@@ -14099,7 +14115,7 @@ def trcnam(index: int, namlen: int = _default_len_out) -> str:
 
 
 @spice_error_check
-def trcoff():
+def trcoff() -> None:
     """
     Disable tracing.
 
@@ -14236,7 +14252,7 @@ def ucrss(v1: ndarray, v2: ndarray) -> ndarray:
     return stypes.c_vector_to_python(vout)
 
 
-def uddc(udfunc, x, dx):
+def uddc(udfunc: UDFUNC, x: float, dx: float) -> bool:
     """
     SPICE private routine intended solely for the support of SPICE
     routines. Users should not call this routine directly due to the
@@ -14255,7 +14271,7 @@ def udfunc(et_in):
             pos, new_et = spice.spkpos("MERCURY", et_in, "J2000", "LT+S", "MOON")
             return new_et
 
-        deriv = spice.uddf(udfunc, et, 1.0)
+        is_negative = spice.uddc(udfunc, et, 1.0)
 
     https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/uddc_c.html
 
@@ -14272,7 +14288,7 @@ def udfunc(et_in):
 
 
 @spice_error_check
-def uddf(udfunc, x, dx):
+def uddf(udfunc: UDFUNC, x: float, dx: float) -> float:
     """
     Routine to calculate the first derivative of a caller-specified
     function using a three-point estimation.

spiceypy/tests/test_wrapper.py

@@ -9774,7 +9774,7 @@ def test_uddc():
     spice.furnsh(CoreKernels.testMetaKernel)
     et = spice.str2et("JAN 1 2009")
 
-    @spiceypy.utils.callbacks.SpiceUDFUNS
+    @spiceypy.utils.callbacks.SpiceUDFUNC
     def udfunc(et_in):
         pos, new_et = spice.spkpos("MERCURY", et_in, "J2000", "LT+S", "MOON")
         return new_et

spiceypy/utils/callbacks.py

@@ -24,8 +24,10 @@
 
 import functools
 from ctypes import c_int, c_double, c_char_p, POINTER, CFUNCTYPE, byref
-from .support_types import SpiceCell
+from .support_types import SpiceCell, SpiceCellPointer, to_python_string
+from typing import Callable, Union
 
+UDFUNC = CFUNCTYPE(None, c_double, POINTER(c_double))
 UDFUNS = CFUNCTYPE(None, c_double, POINTER(c_double))
 UDFUNB = CFUNCTYPE(None, UDFUNS, c_double, POINTER(c_int))
 UDSTEP = CFUNCTYPE(None, c_double, POINTER(c_double))
@@ -36,149 +38,166 @@
 UDBAIL = CFUNCTYPE(c_int)
 
 
-def SpiceUDFUNS(f):
+def SpiceUDFUNC(f: Callable[[float], float]) -> UDFUNC:
+    """
+    Decorator for wrapping python functions in spice udfunc callback type
+
+    :param f: function that has one argument of type float, and returns a float
+    :return: wrapped udfunc function
+    """
+
+    @functools.wraps(f)
+    def wrapping_udfunc(x: float, value: POINTER(c_double)) -> None:
+        result = f(x)
+        value[0] = c_double(result)
+
+    return UDFUNC(wrapping_udfunc)
+
+
+def SpiceUDFUNS(f: Callable[[float], float]) -> UDFUNS:
     """
     Decorator for wrapping python functions in spice udfuns callback type
+
     :param f: function that has one argument of type float, and returns a float
-    :type f: builtins.function
     :return: wrapped udfunc function
-    :rtype: builtins.function
     """
 
     @functools.wraps(f)
-    def wrapping_udfuns(x, value):
+    def wrapping_udfuns(x: float, value: POINTER(c_double)) -> None:
         result = f(x)
         value[0] = c_double(result)
 
     return UDFUNS(wrapping_udfuns)
 
 
-def SpiceUDFUNB(f):
+def SpiceUDFUNB(f: Callable[[UDFUNS, float], int]) -> UDFUNB:
     """
     Decorator for wrapping python functions in spice udfunb callback type
+
     :param f: function to be wrapped
-    :type f: builtins.function
     :return: wrapped udfunb function
-    :rtype: builtins.function
     """
 
     @functools.wraps(f)
-    def wrapping_udfunb(udf, et, xbool):
-        result = f(udf, et)  # the function takes a udffunc as a argument
+    def wrapping_udfunb(udf: UDFUNS, et: float, xbool: POINTER(c_int)) -> None:
+        result = f(udf, et)
         xbool[0] = c_int(result)  # https://github.com/numpy/numpy/issues/14397
 
     return UDFUNB(wrapping_udfunb)
 
 
-def SpiceUDSTEP(f):
+def SpiceUDSTEP(f: Callable[[float], float]) -> UDSTEP:
     """
     Decorator for wrapping python functions in spice udstep callback type
+
     :param f: function to be wrapped
-    :type f: builtins.function
     :return: wrapped udstep function
-    :rtype: builtins.function
     """
 
     @functools.wraps(f)
-    def wrapping_udstep(x, value):
+    def wrapping_udstep(x: float, value: POINTER(c_double)) -> None:
         result = f(x)
         value[0] = c_double(result)
 
     return UDSTEP(wrapping_udstep)
 
 
-def SpiceUDREFN(f):
+def SpiceUDREFN(
+    f: Callable[[float, float, Union[bool, int], Union[bool, int]], float]
+) -> UDREFN:
     """
     Decorator for wrapping python functions in spice udrefn callback type
+
     :param f: function to be wrapped
-    :type f: builtins.function
     :return: wrapped udrefn function
-    :rtype: builtins.function
     """
 
     @functools.wraps(f)
-    def wrapping_udrefn(t1, t2, s1, s2, t):
+    def wrapping_udrefn(
+        t1: float,
+        t2: float,
+        s1: Union[bool, int],
+        s2: Union[bool, int],
+        t: POINTER(c_double),
+    ) -> None:
         result = f(t1, t2, s1, s2)
         t[0] = c_double(result)
 
     return UDREFN(wrapping_udrefn)
 
 
-def SpiceUDREPI(f):
+def SpiceUDREPI(
+    f: Callable[[Union[SpiceCell, SpiceCellPointer], str, str], None]
+) -> UDREPI:
     """
     Decorator for wrapping python functions in spice udfrepi callback type
+
     :param f: function to be wrapped
-    :type f: builtins.function
     :return: wrapped udrepi function
-    :rtype: builtins.function
     """
 
     @functools.wraps(f)
-    def wrapping_udrepi(cnfine, srcpre, srcsurf):
-        f(cnfine, srcpre, srcsurf)
+    def wrapping_udrepi(
+        cnfine: Union[SpiceCell, SpiceCellPointer], srcpre: bytes, srcsurf: bytes
+    ) -> None:
+        f(cnfine, to_python_string(srcpre), to_python_string(srcsurf))
 
     return UDREPI(wrapping_udrepi)
 
 
-def SpiceUDREPU(f):
+def SpiceUDREPU(f: Callable[[float, float, float], None]) -> UDREPU:
     """
     Decorator for wrapping python functions in spice udrepu callback type
+
     :param f: function to be wrapped
-    :type f: builtins.function
     :return: wrapped udrepu function
-    :rtype: builtins.function
     """
 
     @functools.wraps(f)
-    def wrapping_udrepu(beg, end, et):
+    def wrapping_udrepu(beg: float, end: float, et: float) -> None:
         f(beg, end, et)
 
     return UDREPU(wrapping_udrepu)
 
 
-def SpiceUDREPF(f):
+def SpiceUDREPF(f: Callable) -> UDREPF:
     """
     Decorator for wrapping python functions in spice udrepf callback type
+
     :param f: function to be wrapped
-    :type f: builtins.function
     :return: wrapped udrepf function
-    :rtype: builtins.function
     """
 
     @functools.wraps(f)
-    def wrapping_udrepf():
+    def wrapping_udrepf() -> None:
         f()
 
     return UDREPF(wrapping_udrepf)
 
 
-def SpiceUDBAIL(f):
+def SpiceUDBAIL(f: Callable[[], Union[bool, int]]) -> UDBAIL:
     """
     Decorator for wrapping python functions in spice udbail callback type
+
     :param f: function to be wrapped
-    :type f: builtins.function
     :return: wrapped udbail function
-    :rtype: builtins.function
     """
 
     @functools.wraps(f)
-    def wrapping_udbail():
+    def wrapping_udbail() -> int:
         result = f()
         return int(result)
 
     return UDBAIL(wrapping_udbail)
 
 
-def CallUDFUNS(f, x):
+def CallUDFUNS(f: UDFUNS, x: float) -> float:
     """
     We are given a UDF CFUNCTYPE and want to call it in python
 
     :param f: SpiceUDFUNS
-    :type f: CFUNCTYPE
     :param x: some scalar
-    :type x: float
     :return: value
-    :rtype: float
     """
     value = c_double()
     f(x, byref(value))

spiceypy/utils/support_types.py

@@ -61,6 +61,7 @@
     cast,
     Structure,
     string_at,
+    POINTER,
 )
 
 import numpy
@@ -1028,6 +1029,8 @@ def __eq__(self, other):
         return True
 
 
+SpiceCellPointer = POINTER(SpiceCell)
+
 # Spice Cell classes