rename devices as sources

docs/api/sources.md

@@ -0,0 +1,11 @@
+# sources
+
+Interfaces to external source devices like miniscopes and DAQs
+
+## OpalKelly
+
+```{eval-rst}
+.. autoclass:: miniscope_io.sources.opalkelly.okDev
+    :members:
+    :undoc-members:
+```

docs/index.md

@@ -21,13 +21,13 @@ device/test_device
 :maxdepth: 1
 :caption: API:
 
-api/devices
 api/formats/index
 api/io
 api/logging
 api/models/index
 api/exceptions
 api/plots/index
+api/sources
 api/utils
 api/stream_daq
 api/bit_operation

docs/meta/changelog.md

@@ -77,7 +77,7 @@ StreamDaq enhancements and testing
 Testing:
 
 - [@t-sasatani](https://github.com/t-sasatani) - add end-to-end test for {class}`~miniscope_io.stream_daq.streamDaq`
-- Add a mock class for {class}`~miniscope_io.devices.opalkelly.okDev`
+- Add a mock class for {class}`~miniscope_io.sources.opalkelly.okDev`
 - replace `tmpdir` fixture and `tempfile` module with `tmp_path`
 
 New:
@@ -95,7 +95,7 @@ New:
 
 Fixed:
 
-- Removed `print` statements in {class}`~miniscope_io.devices.opalkelly.okDev`
+- Removed `print` statements in {class}`~miniscope_io.sources.opalkelly.okDev`
 - {meth}`~miniscope_io.stream_daq.StreamDaq.capture`
   - Don't require `config`
   - Replace logging with {func}`~miniscope_io.logging.init_logger`
@@ -137,7 +137,7 @@ New features:
 
 - Added support for the wireless FPGA and UART daqs - work in progress unifying the API, but
   initial version of code is present in `stream_daq.py`
-- Vendored opalkelly device drivers - see `devices` and `vendor`
+- Vendored opalkelly device drivers - see `devices` (now `sources`) and `vendor`
 
 ### 0.1.5 - 23-09-03
 

miniscope_io/__init__.py

@@ -11,7 +11,7 @@
 BASE_DIR = Path(__file__).parent.resolve()
 DATA_DIR = BASE_DIR / "data"
 CONFIG_DIR = DATA_DIR / "config"
-DEVICE_DIR = BASE_DIR / "devices"
+DEVICE_DIR = BASE_DIR / "sources"
 
 __all__ = [
     "BASE_DIR",

miniscope_io/cameras/__init__.py

@@ -0,0 +1,3 @@
+"""
+Camera classes :)
+"""

miniscope_io/cameras/camera.py

@@ -0,0 +1,17 @@
+"""
+ABCs for Camera and Miniscope source classes
+"""
+
+from miniscope_io.models import Source
+
+
+class Camera(Source):
+    """
+    A data source that captures images, often in a sequence known as a "video"
+    """
+
+
+class Miniscope(Camera):
+    """
+    A miniature microscope
+    """

miniscope_io/exceptions.py

@@ -42,7 +42,7 @@ class StreamReadError(StreamError):
 
 class DeviceError(RuntimeError):
     """
-    Base class for errors when communicating with or configuring devices
+    Base class for errors when communicating with or configuring sources
     """
 
 

miniscope_io/sources/__init__.py

@@ -0,0 +1,3 @@
+"""
+Control interfaces for external hardware sources
+"""

miniscope_io/devices/mocks.py → miniscope_io/sources/mocks.py

@@ -1,7 +1,7 @@
 """
-Hardware mocks for devices.
+Hardware mocks for sources.
 
-Used in testing, but kept in-package since for now some devices
+Used in testing, but kept in-package since for now some sources
 need modifications to their source (and we can't import from tests)
 
 Not to be considered part of the public interface of miniscope-io <3
@@ -18,7 +18,7 @@
 
 class okDevMock:
     """
-    Mock class for :class:`~miniscope_io.devices.opalkelly.okDev`
+    Mock class for :class:`~miniscope_io.sources.opalkelly.okDev`
     """
 
     DATA_FILE: Optional[Path] = None

miniscope_io/stream_daq.py

@@ -17,7 +17,6 @@
 
 from miniscope_io import init_logger
 from miniscope_io.bit_operation import BufferFormatter
-from miniscope_io.devices.mocks import okDevMock
 from miniscope_io.exceptions import EndOfRecordingException, StreamReadError
 from miniscope_io.formats.stream import StreamBufferHeader as StreamBufferHeaderFormat
 from miniscope_io.io import BufferedCSVWriter
@@ -29,11 +28,12 @@
     StreamBufferHeaderFormat as StreamBufferHeaderFormatType,
 )
 from miniscope_io.plots.headers import StreamPlotter
+from miniscope_io.sources.mocks import okDevMock
 
 HAVE_OK = False
 ok_error = None
 try:
-    from miniscope_io.devices.opalkelly import okDev
+    from miniscope_io.sources.opalkelly import okDev
 
     HAVE_OK = True
 except (ImportError, ModuleNotFoundError):
@@ -61,7 +61,7 @@ def exact_iter(f: Callable, sentinel: Any) -> Generator[Any, None, None]:
 class StreamDaq:
     """
     A combined class for configuring and reading frames from a UART and FPGA source.
-    Supported devices and required inputs are described in StreamDevConfig model documentation.
+    Supported sources and required inputs are described in StreamDevConfig model documentation.
     This function's entry point is the main function, which should be used from the
     stream_image_capture command installed with the package.
     Example configuration yaml files are stored in /miniscope-io/config/.
@@ -70,7 +70,7 @@ class StreamDaq:
     --------
     $ mio stream capture -c path/to/config.yml -o output_filename.avi
     Connected to XEM7310-A75
-    Succesfully uploaded /miniscope-io/miniscope_io/devices/selected_bitfile.bit
+    Succesfully uploaded /miniscope-io/miniscope_io/sources/selected_bitfile.bit
     FrontPanel is supported
 
     .. todo::

pyproject.toml

@@ -95,7 +95,7 @@ timeout = 60
 [tool.coverage.run]
 omit = [
     "miniscope_io/vendor/*",
-    "miniscope_io/devices/opalkelly.py", # can't test hardware interface directly
+    "miniscope_io/sources/opalkelly.py", # can't test hardware interface directly
 ]
 
 [tool.ruff]

tests/conftest.py

@@ -25,8 +25,8 @@ def pytest_sessionstart(session):
 
 @pytest.fixture(autouse=True)
 def mock_okdev(monkeypatch):
-    from miniscope_io.devices.mocks import okDevMock
-    from miniscope_io.devices import opalkelly
+    from miniscope_io.sources.mocks import okDevMock
+    from miniscope_io.sources import opalkelly
     from miniscope_io import stream_daq
 
     monkeypatch.setattr(opalkelly, "okDev", okDevMock)
@@ -41,7 +41,7 @@ def set_okdev_input(monkeypatch):
     """
 
     def _set_okdev_input(file: Union[str, Path]):
-        from miniscope_io.devices.mocks import okDevMock
+        from miniscope_io.sources.mocks import okDevMock
 
         monkeypatch.setattr(okDevMock, "DATA_FILE", file)
         os.environ["PYTEST_OKDEV_DATA_FILE"] = str(file)

tests/test_models/test_model_stream.py

@@ -25,7 +25,7 @@ def test_preamble_hex_parsing(config):
 
 def test_absolute_bitstream():
     """
-    Relative paths should be resolved relative to the devices dir
+    Relative paths should be resolved relative to the sources dir
     """
     example = CONFIG_DIR / "wireless_example.yml"