poulet-py 0.1.2__py3-none-any.whl

poulet_py/__init__.py

@@ -0,0 +1,3 @@
+from lazy_loader import attach_stub
+
+__getattr__, __dir__, __all__ = attach_stub(__name__, __file__)

poulet_py/__init__.pyi

@@ -0,0 +1,46 @@
+# ruff: noqa TID252
+from .config import LOGGER, SETTINGS, Settings, setup_logging
+from .converters import Seq
+from .hardware import (
+    TCS,
+    Arduino,
+    BaslerCamera,
+    JulaboChiller,
+    TCSCommand,
+    TCSStimulus,
+    ThermalCamera,
+)
+from .tools import (
+    check_or_create,
+    define_folder_name,
+    generate_stimulus_sequence,
+    go_to,
+    json_serializer,
+    sanitize_path,
+    save_metadata_exp,
+)
+from .utils import Oscilloscope, TCSInterface
+
+__all__ = [
+    "LOGGER",
+    "SETTINGS",
+    "TCS",
+    "Arduino",
+    "BaslerCamera",
+    "JulaboChiller",
+    "Oscilloscope",
+    "Seq",
+    "Settings",
+    "TCSCommand",
+    "TCSInterface",
+    "TCSStimulus",
+    "ThermalCamera",
+    "check_or_create",
+    "define_folder_name",
+    "generate_stimulus_sequence",
+    "go_to",
+    "json_serializer",
+    "sanitize_path",
+    "save_metadata_exp",
+    "setup_logging",
+]

poulet_py/config/__init__.py

@@ -0,0 +1,3 @@
+from lazy_loader import attach_stub
+
+__getattr__, __dir__, __all__ = attach_stub(__name__, __file__)

poulet_py/config/__init__.pyi

@@ -0,0 +1,5 @@
+# ruff: noqa TID252
+from .logging import LOGGER, setup_logging
+from .settings import SETTINGS, Settings
+
+__all__ = ["LOGGER", "SETTINGS", "Settings", "setup_logging"]

poulet_py/config/logging.py

@@ -0,0 +1,94 @@
+from logging import FileHandler, Formatter, Logger, getLogger
+
+from rich.console import Console
+from rich.logging import RichHandler
+
+from poulet_py.config.settings import SETTINGS
+
+
+def setup_logging(
+    logger: Logger,
+    *,
+    terminal_width: int | None = None,
+    show_time: bool = False,
+    show_path: bool = True,
+    markup: bool = True,
+    rich_tracebacks: bool = True,
+    tracebacks_extra_lines: int = 4,
+    tracebacks_word_wrap: bool = True,
+    tracebacks_show_locals: bool = True,
+    level: int | str = "warning",
+    file: str | None = None,
+) -> None:
+    """
+    Configure logging for the provided logger with optional rich formatting
+    and file logging.
+
+    Parameters
+    ----------
+    logger : Logger
+        The logger instance to configure.
+    terminal_width : int, optional
+        The width of the terminal for rich console output.
+        If None, the default width is used.
+    show_time : bool, optional
+        Whether to show the time in the log output. Default is False.
+    show_path : bool, optional
+        Whether to show the path in the log output. Default is True.
+    markup : bool, optional
+        Whether to enable markup in the log output. Default is True.
+    rich_tracebacks : bool, optional
+        Whether to enable rich tracebacks. Default is True.
+    tracebacks_extra_lines : int, optional
+        Number of extra lines to show in tracebacks. Default is 4.
+    tracebacks_word_wrap : bool, optional
+        Whether to enable word wrap in tracebacks. Default is True.
+    tracebacks_show_locals : bool, optional
+        Whether to show local variables in tracebacks. Default is True.
+    level : int or str, optional
+        The logging level to set for the logger. Default is warning.
+    file : str, optional
+        The file to log to. If None, logs are output to the console.
+
+    Returns
+    -------
+    None
+    """
+    if file is not None:
+        file_handler = FileHandler(file)
+        file_handler.setFormatter(Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
+        logger.addHandler(file_handler)
+    else:
+        console = Console(width=terminal_width) if terminal_width else Console()
+        rich_handler = RichHandler(
+            show_time=show_time,
+            show_level=True,
+            rich_tracebacks=rich_tracebacks,
+            tracebacks_show_locals=tracebacks_show_locals,
+            tracebacks_word_wrap=tracebacks_word_wrap,
+            tracebacks_extra_lines=tracebacks_extra_lines,
+            markup=markup,
+            show_path=show_path,
+            console=console,
+        )
+        rich_handler.setFormatter(Formatter("%(message)s"))
+        logger.addHandler(rich_handler)
+
+    logger.setLevel(level.upper())
+    logger.propagate = False
+
+
+# Global instance of the `logger` object
+LOGGER = getLogger()
+setup_logging(LOGGER, level=SETTINGS.log.level, file=SETTINGS.log.file)
+"""
+An instance of the `logger` object.
+
+This instance holds can be imported and used throughout the application
+for logging.
+
+Example
+-------
+>>> from poulet_py.config.logging import LOGGER
+>>> LOGGER.warning("This is a warning message.")
+"""

poulet_py/config/settings.py

@@ -0,0 +1,90 @@
+"""
+Configuration settings.
+
+This module defines the application's configuration settings using Pydantic's
+`BaseSettings` and `BaseModel`. It supports loading configuration from environment
+variables and a `.env` file.
+
+Usage Examples
+--------------
+1. Accessing Default Settings:
+    >>> from poulet_py.config.settings import settings
+    >>> print(settings.log.level)  # Output: "info"
+    >>> print(settings.log.file)  # Output: None
+
+2. Overriding Settings with Environment Variables:
+    Set environment variables before running the application:
+    ```bash
+    export LOG__LEVEL="debug"
+    export LOG__FILE="/var/log/myapp.log"
+    ```
+    Then access the settings in your code:
+    >>> from poulet_py.config.settings import settings
+    >>> print(settings.log.level)  # Output: "debug"
+    >>> print(settings.log.file)  # Output: "/var/log/myapp.log"
+
+3. Loading Settings from a `.env` File:
+    Create a `.env` file in the project root:
+    ```env
+    LOG__LEVEL=warning
+    LOG__FILE=/tmp/app.log
+    ```
+    Then access the settings in your code:
+    >>> from poulet_py.config.settings import settings
+    >>> print(settings.log.level)  # Output: "warning"
+    >>> print(settings.log.file)  # Output: "/tmp/app.log"
+
+4. Programmatically Updating Settings:
+    >>> from poulet_py.config.settings import Settings
+    >>> custom_settings = Settings(log={"level": "error", "file": "/custom/path.log"})
+    >>> print(custom_settings.log.level)  # Output: "error"
+    >>> print(custom_settings.log.file)  # Output: "/custom/path.log"
+"""
+
+from dotenv import find_dotenv
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Log(BaseModel):
+    level: str = Field("info", description="The logging level")
+    file: str | None = Field(
+        None,
+        description="""The file path for logging. If `None`,
+        logging is done to the console.
+        """,
+    )
+
+
+class Settings(BaseSettings):
+    """
+    This class loads configuration from environment variables and a `.env` file.
+    It supports nested configuration using the `env_nested_delimiter`
+    (e.g., `LOG__LEVEL`).
+    """
+
+    model_config = SettingsConfigDict(
+        env_nested_delimiter="__",
+        env_file=find_dotenv(),
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+    log: Log = Field(Log(), description="Logging configuration settings")
+
+
+# Global instance of the `Settings` class
+SETTINGS = Settings()
+"""
+An instance of the `Settings` class.
+
+This instance holds the application's configuration, loaded from environment
+variables and a `.env` file.
+It can be imported and used throughout the application to access
+configuration settings.
+
+Example
+-------
+To access the logging level:
+>>> from poulet_py.config.settings import SETTINGS
+>>> print(SETTINGS.log.level)
+"""

poulet_py/converters/__init__.py

@@ -0,0 +1,3 @@
+from lazy_loader import attach_stub
+
+__getattr__, __dir__, __all__ = attach_stub(__name__, __file__)

poulet_py/converters/__init__.pyi

@@ -0,0 +1,4 @@
+# ruff: noqa TID252
+from .seq import Seq
+
+__all__ = ["Seq"]

poulet_py/converters/seq.py

@@ -0,0 +1,147 @@
+try:
+    from pathlib import Path
+    from pickle import HIGHEST_PROTOCOL
+    from typing import Any
+
+    from flirpy.io.fff import Fff
+    from flirpy.io.seq import Seq as SeqBase
+    from h5py import File
+    from numpy import array, ndarray
+    from pandas._typing import CompressionOptions
+    from pandas.io.pickle import to_pickle as pd_to_pickle
+except ImportError as e:
+    msg = """
+Missing 'seq' module. Install options:
+- Dedicated:    pip install poulet_py[seq]
+- Module:       pip install poulet_py[converters]
+- Full:         pip install poulet_py[all]
+"""
+    raise ImportError(msg) from e
+
+
+class Seq(SeqBase):
+    """A sequence handler for FLIR thermal data with export capabilities.
+
+    Extends `flirpy.io.seq.Seq` to add NumPy, HDF5, and pickle serialization.
+
+    Parameters
+    ----------
+    input_file : str | Path
+        Path to the input SEQ file.
+    height : int, optional
+        Force a specific image height. If None, uses the file's metadata.
+    width : int, optional
+        Force a specific image width. If None, uses the file's metadata.
+    raw : bool, default=False
+        If True, returns the raw bytes not Fff class.
+    """
+
+    def __init__(
+        self,
+        input_file: str | Path,
+        *,
+        height: int | None = None,
+        width: int | None = None,
+        raw: bool = False,
+    ):
+        super().__init__(input_file, height=height, width=width, raw=raw)
+
+    def to_list(self) -> list:
+        """Convert the sequence to a list of frames.
+
+        Returns
+        -------
+        list
+            List of frames (as ndarray or bytes if unprocessed).
+        """
+        return [frame.get_image() if isinstance(frame, Fff) else frame for frame in self]
+
+    def to_numpy(self, *, dtype: type | None = None) -> ndarray:
+        """Convert the sequence to a NumPy array.
+
+        Parameters
+        ----------
+        dtype : type, optional
+            Desired data type for the output array (e.g., `np.float32`).
+
+        Returns
+        -------
+        ndarray
+            Stacked frames as a 3D array (n_frames, height, width).
+        """
+        return array(self.to_list(), dtype=dtype)
+
+    def to_hdf(
+        self,
+        path: str | Path,
+        *,
+        key,
+        mode="w",
+        dtype: type | None = None,
+        complib=None,
+        complevel=None,
+        meta: dict[str, Any] | None = None,
+    ):
+        """Save the sequence to an HDF5 file.
+
+        Parameters
+        ----------
+        path : str | Path
+            Output file path.
+        key : str
+            HDF5 dataset name.
+        mode : str, default="w"
+            File mode ('w', 'a', 'r+', etc.).
+        dtype : type, optional
+            Data type for the stored array.
+        complib : str, optional
+            Compression library (e.g., 'gzip', 'lzf').
+        complevel : int, optional
+            Compression level (1-9 for gzip).
+        meta : dict, optional
+            Metadata to store as HDF5 attributes.
+        """
+        data = self.to_numpy(dtype=dtype)
+        with File(path, mode) as f:
+            ds = f.create_dataset(key, data=data, compression=complib, compression_opts=complevel)
+
+            if meta:
+                for k, v in meta.items():
+                    ds.attrs[k] = v
+
+    def to_pickle(
+        self,
+        path: str | Path,
+        *,
+        dtype: type | None = None,
+        compression: CompressionOptions = "infer",
+        protocol: int = HIGHEST_PROTOCOL,
+    ):
+        """Save the sequence to a pickle file using pandas' I/O handler.
+
+        Parameters
+        ----------
+        path : str | Path
+            Output file path.
+        dtype : type, optional
+            Data type for the array.
+        compression : str or dict, default 'infer'
+            For on-the-fly compression of the output data.
+            If 'infer' and 'path' is path-like,
+            then detect compression from the following extensions:
+            '.gz', '.bz2', '.zip', '.xz', '.zst', '.tar', '.tar.gz', '.tar.xz' or '.tar.bz2'
+            (otherwise no compression).
+            Set to None for no compression.
+            Can also be a dict with key 'method'
+            set to one of {'zip', 'gzip', 'bz2', 'zstd', 'xz', 'tar'}
+            and other key-value pairs are forwarded to zipfile.ZipFile,
+            gzip.GzipFile, bz2.BZ2File, zstandard.ZstdCompressor,
+            lzma.LZMAFile or tarfile.TarFile, respectively.
+            As an example, the following could be passed for faster compression
+            and to create a reproducible gzip archive:
+            compression={'method': 'gzip', 'compresslevel': 1, 'mtime': 1}
+        protocol : int, default=HIGHEST_PROTOCOL
+            Pickle protocol version.
+        """
+        data = self.to_numpy(dtype=dtype)
+        pd_to_pickle(data, path, compression=compression, protocol=protocol)

poulet_py/hardware/__init__.py

@@ -0,0 +1,3 @@
+from lazy_loader import attach_stub
+
+__getattr__, __dir__, __all__ = attach_stub(__name__, __file__)

poulet_py/hardware/__init__.pyi

@@ -0,0 +1,13 @@
+# ruff: noqa TID252
+from .camera import BaslerCamera, ThermalCamera
+from .stimulator import TCS, Arduino, JulaboChiller, TCSCommand, TCSStimulus
+
+__all__ = [
+    "TCS",
+    "Arduino",
+    "BaslerCamera",
+    "JulaboChiller",
+    "TCSCommand",
+    "TCSStimulus",
+    "ThermalCamera",
+]

poulet_py/hardware/camera/__init__.py

@@ -0,0 +1,3 @@
+from lazy_loader import attach_stub
+
+__getattr__, __dir__, __all__ = attach_stub(__name__, __file__)

poulet_py/hardware/camera/__init__.pyi

@@ -0,0 +1,5 @@
+# ruff: noqa TID252
+from .basler import BaslerCamera
+from .thermal_camera import ThermalCamera
+
+__all__ = ["BaslerCamera", "ThermalCamera"]