Move to a src layout and ship type information

MANIFEST.in

@@ -2,7 +2,7 @@ include README.md
 include LICENSE
 include setup.py
 include pyproject.toml
-include extinction.pyx
+recursive-include src *.pyx *.pyi py.typed
 include extern/bs.*
 include extern/bsplines.pxi
 include test.py

pyproject.toml

@@ -40,10 +40,21 @@ Homepage = "https://github.com/sncosmo/extinction"
 Documentation = "https://extinction.readthedocs.io"
 Source = "https://github.com/sncosmo/extinction"
 
-# extinction is a single compiled module, so disable package auto-discovery,
-# which would otherwise trip over the docs/, extern/ and testdata/ directories.
 [tool.setuptools]
-py-modules = []
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# PEP 561 marker and stubs for the compiled module.
+[tool.setuptools.package-data]
+extinction = ["py.typed", "*.pyi"]
+
+# The Cython source and its generated C belong in the sdist, not in binary
+# wheels; now that they live inside the package directory, MANIFEST.in would
+# otherwise pull them in.
+[tool.setuptools.exclude-package-data]
+extinction = ["*.pyx", "*.c"]
 
 [tool.cibuildwheel]
 test-requires = "pytest"

setup.py

@@ -8,9 +8,11 @@
 from setuptools import setup
 from setuptools.extension import Extension
 
+here = os.path.dirname(os.path.abspath(__file__))
+
 # Everything except the version and the extension itself lives in
 # pyproject.toml. Synchronize the version from code.
-fname = "extinction.pyx"
+fname = os.path.join("src", "extinction", "_extinction.pyx")
 version = re.findall(r"__version__ = \"(.*?)\"", open(fname).read())[0]
 
 # Build Cython extension
@@ -26,7 +28,7 @@
 
 extensions = [
     Extension(
-        "extinction",
+        "extinction._extinction",
         source_files,
         include_dirs=include_dirs,
         depends=depends_files,
@@ -36,5 +38,7 @@
 
 setup(
     version=version,
-    ext_modules=cythonize(extensions, language_level=3),
+    # `include "extern/bsplines.pxi"` in the .pyx resolves against the project
+    # root, not the directory holding the .pyx.
+    ext_modules=cythonize(extensions, language_level=3, include_path=[here]),
 )

src/extinction/__init__.py

@@ -0,0 +1,16 @@
+"""Interstellar dust extinction functions."""
+
+from extinction._extinction import (
+    Fitzpatrick99,
+    __version__,
+    apply,
+    calzetti00,
+    ccm89,
+    fitzpatrick99,
+    fm07,
+    odonnell94,
+    remove,
+)
+
+__all__ = ['ccm89', 'odonnell94', 'Fitzpatrick99', 'fitzpatrick99', 'fm07',
+           'calzetti00', 'apply', 'remove', '__version__']

src/extinction/_extinction.pyi

@@ -0,0 +1,57 @@
+from typing import Literal
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+__version__: str
+__all__: list[str]
+
+_Unit = Literal["aa", "invum"]
+_Array = NDArray[np.float64]
+
+def ccm89(
+    wave: _Array,
+    a_v: float,
+    r_v: float,
+    unit: _Unit = ...,
+    out: _Array | None = ...,
+) -> _Array: ...
+def odonnell94(
+    wave: _Array,
+    a_v: float,
+    r_v: float,
+    unit: _Unit = ...,
+    out: _Array | None = ...,
+) -> _Array: ...
+def calzetti00(
+    wave: _Array,
+    a_v: float,
+    r_v: float,
+    unit: _Unit = ...,
+    out: _Array | None = ...,
+) -> _Array: ...
+def fitzpatrick99(
+    wave: _Array,
+    a_v: float,
+    r_v: float = ...,
+    unit: _Unit = ...,
+) -> _Array: ...
+def fm07(wave: _Array, a_v: float, unit: _Unit = ...) -> _Array: ...
+
+class Fitzpatrick99:
+    # cdef readonly in the extension: assignment raises AttributeError.
+    @property
+    def r_v(self) -> float: ...
+    def __init__(self, r_v: float = ...) -> None: ...
+    def __call__(
+        self, wave: _Array, a_v: float, unit: _Unit = ...
+    ) -> _Array: ...
+
+# Unlike the wavelength arguments above, which go through typed memoryviews,
+# these are plain numpy arithmetic and accept any array-like of any dtype.
+def apply(
+    extinction: ArrayLike, flux: ArrayLike, inplace: bool = ...
+) -> _Array: ...
+def remove(
+    extinction: ArrayLike, flux: ArrayLike, inplace: bool = ...
+) -> _Array: ...