TwoPy 0.4.0__tar.gz → 0.4.1__tar.gz

{twopy-0.4.0 → twopy-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: twopy
-Version: 0.4.0
+Version: 0.4.1
 Summary: Two-photon imaging analysis tool with a napari interface.
 Author-email: Gustavo Madeira Santana <fromweb1@gumadeiras.com>
 License-Expression: MIT

{twopy-0.4.0 → twopy-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "twopy"
-version = "0.4.0"
+version = "0.4.1"
 description = "Two-photon imaging analysis tool with a napari interface."
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{twopy-0.4.0 → twopy-0.4.1}/src/twopy/api.py

@@ -1,6 +1,6 @@
 """Public script-friendly API for twopy.
 
-Inputs: simple Python arguments such as year, genotype, stimulus, and paths.
+Inputs: simple Python arguments such as date, genotype, stimulus, and paths.
 Outputs: typed twopy objects returned by lower-level modules.
 
 This module is the stable place for scripts to import from. It keeps scripts away
@@ -19,9 +19,7 @@ __all__ = ["find_recordings", "finite_mean_and_sem"]
 
 def find_recordings(
     *,
-    year: int | None = None,
-    month: int | None = None,
-    day: int | None = None,
+    date: str | None = None,
     genotype: str | None = None,
     stimulus: str | None = None,
     sensor: str | None = None,
@@ -36,9 +34,7 @@ def find_recordings(
     """Find recording experiments using the configured lab database path.
 
     Args:
-        year: Optional experiment year.
-        month: Optional experiment month.
-        day: Optional experiment day-of-month.
+        date: Optional date expression with selectors and inclusive ranges.
         genotype: Optional genotype substring.
         stimulus: Optional stimulus-function substring.
         sensor: Optional sensor substring from fly ``fluorescentProtein``.
@@ -58,7 +54,7 @@ def find_recordings(
         Typed recording experiment rows.
 
     Example:
-        ``find_recordings(year=2023, month=10, genotype="gh146")``
+        ``find_recordings(date="2023-10", genotype="gh146")``
 
     The function loads twopy config by default so scripts can start with a
     single import and call after ``twopy config setup``.
@@ -66,9 +62,7 @@ def find_recordings(
     config = load_config(config_path)
     return _find_recordings(
         config.database_path,
-        year=year,
-        month=month,
-        day=day,
+        date=date,
         genotype=genotype,
         stimulus=stimulus,
         sensor=sensor,

twopy-0.4.1/src/twopy/database/date_filters.py

@@ -0,0 +1,294 @@
+"""Parse explicit date expressions for recording database searches.
+
+Inputs: date filter text from the search dialog or scripting API.
+Outputs: validated selectors for safe, parameterized database queries.
+
+The parser keeps date meaning separate from SQLite text matching. This makes
+lists, partial dates, and inclusive ranges clear before a query starts.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import date
+from typing import Literal
+
+EXPERIMENT_DATE_FILTER_HELP = (
+    "Use YYYY, YYYY-MM, MM-DD, or YYYY-MM-DD.\n"
+    "Separate selections with commas. Use two full dates with '..' for an "
+    "inclusive range.\n"
+    "Date parts accept '-', '/', '\\', '.', or '_'."
+)
+
+_DATE_SEPARATOR = r"[-/\\._]"
+_YEAR_PATTERN = re.compile(r"^(\d{4})$")
+_YEAR_MONTH_PATTERN = re.compile(rf"^(\d{{4}}){_DATE_SEPARATOR}(\d{{1,2}})$")
+_MONTH_DAY_PATTERN = re.compile(rf"^(\d{{1,2}}){_DATE_SEPARATOR}(\d{{1,2}})$")
+_FULL_DATE_PATTERN = re.compile(
+    rf"^(\d{{4}}){_DATE_SEPARATOR}(\d{{1,2}}){_DATE_SEPARATOR}(\d{{1,2}})$"
+)
+
+DateSelectorKind = Literal["year", "year_month", "month_day", "date"]
+
+
+@dataclass(frozen=True)
+class ExperimentDateSelector:
+    """One validated date or partial-date selection.
+
+    Args:
+        kind: Date parts that take part in the database comparison.
+        year: Four-digit year when ``kind`` includes a year.
+        month: Month number when ``kind`` includes a month.
+        day: Day number when ``kind`` includes a day.
+
+    Outputs:
+        Immutable date parts with a canonical user-facing representation.
+
+    The explicit kind prevents a partial date from becoming an arbitrary text
+    match in the database.
+    """
+
+    kind: DateSelectorKind
+    year: int | None = None
+    month: int | None = None
+    day: int | None = None
+
+    def __post_init__(self) -> None:
+        """Validate the date parts required by the selector kind."""
+        expected_parts = {
+            "year": (True, False, False),
+            "year_month": (True, True, False),
+            "month_day": (False, True, True),
+            "date": (True, True, True),
+        }[self.kind]
+        actual_parts = (
+            self.year is not None,
+            self.month is not None,
+            self.day is not None,
+        )
+        if actual_parts != expected_parts:
+            msg = f"Date selector {self.kind!r} has incorrect date parts."
+            raise ValueError(msg)
+
+        validation_year = self.year if self.year is not None else 2000
+        validation_month = self.month if self.month is not None else 1
+        validation_day = self.day if self.day is not None else 1
+        date(validation_year, validation_month, validation_day)
+
+    @property
+    def normalized(self) -> str:
+        """Return the selector with zero-padded date parts.
+
+        Returns:
+            Canonical text for display, comparison, and favorite storage.
+
+        The canonical text makes equivalent separators and padding compare as
+        one saved filter.
+        """
+        if self.kind == "year":
+            assert self.year is not None
+            return f"{self.year:04d}"
+        if self.kind == "year_month":
+            assert self.year is not None and self.month is not None
+            return f"{self.year:04d}-{self.month:02d}"
+        if self.kind == "month_day":
+            assert self.month is not None and self.day is not None
+            return f"{self.month:02d}-{self.day:02d}"
+        assert self.year is not None and self.month is not None and self.day is not None
+        return f"{self.year:04d}-{self.month:02d}-{self.day:02d}"
+
+
+@dataclass(frozen=True)
+class ExperimentDateRange:
+    """One inclusive range between two full recording dates.
+
+    Args:
+        start: First accepted calendar date.
+        end: Last accepted calendar date.
+
+    Outputs:
+        Immutable ordered endpoints with a canonical representation.
+
+    The full-date endpoints make inclusion of the final recording day
+    unambiguous.
+    """
+
+    start: date
+    end: date
+
+    def __post_init__(self) -> None:
+        """Reject a range whose start follows its end."""
+        if self.start > self.end:
+            msg = (
+                f"Date range start {self.start.isoformat()} follows "
+                f"{self.end.isoformat()}."
+            )
+            raise ValueError(msg)
+
+    @property
+    def normalized(self) -> str:
+        """Return the range with canonical full-date endpoints.
+
+        Returns:
+            ``YYYY-MM-DD..YYYY-MM-DD`` text.
+
+        This text preserves the inclusive range operator used by the search
+        field.
+        """
+        return f"{self.start.isoformat()}..{self.end.isoformat()}"
+
+
+ExperimentDateFilterItem = ExperimentDateSelector | ExperimentDateRange
+
+
+@dataclass(frozen=True)
+class ExperimentDateFilter:
+    """One validated list of date selectors and inclusive ranges.
+
+    Args:
+        items: Non-empty tuple of date selections joined with logical ``OR``.
+
+    Outputs:
+        Immutable query input with canonical text for the search field.
+
+    The filter groups all items into one database condition. Other search
+    fields can then combine with that condition using logical ``AND``.
+    """
+
+    items: tuple[ExperimentDateFilterItem, ...]
+
+    def __post_init__(self) -> None:
+        """Require at least one date selection."""
+        if len(self.items) == 0:
+            msg = "A date filter must contain at least one selector."
+            raise ValueError(msg)
+
+    @property
+    def normalized(self) -> str:
+        """Return canonical comma-separated filter text.
+
+        Returns:
+            Normalized selectors in their entered order.
+
+        Favorites use this text so equivalent separators and spacing compare
+        equally.
+        """
+        return ", ".join(item.normalized for item in self.items)
+
+
+def parse_experiment_date_filter(value: str | None) -> ExperimentDateFilter | None:
+    r"""Parse one database-search date expression.
+
+    Args:
+        value: Optional date filter text from the dialog or scripting API.
+
+    Returns:
+        Validated selectors, or ``None`` when the input is blank.
+
+    Raises:
+        ValueError: If any selector, date, or range is invalid.
+
+    This parser accepts ``-``, ``/``, ``\``, ``.``, and ``_`` separators. It
+    rejects invalid input before any database query starts.
+    """
+    if value is None or value.strip() == "":
+        return None
+
+    items: list[ExperimentDateFilterItem] = []
+    for index, raw_item in enumerate(value.strip().split(","), start=1):
+        item = raw_item.strip()
+        if item == "":
+            raise _date_filter_error(item, f"selector {index} is empty")
+        items.append(_parse_date_filter_item(item))
+    return ExperimentDateFilter(tuple(items))
+
+
+def _parse_date_filter_item(value: str) -> ExperimentDateFilterItem:
+    """Return one validated partial date, full date, or range."""
+    if ".." not in value:
+        return _parse_date_selector(value)
+    if value.count("..") != 1:
+        raise _date_filter_error(value, "a range must contain one '..' operator")
+
+    raw_start, raw_end = (part.strip() for part in value.split("..", maxsplit=1))
+    if raw_start == "" or raw_end == "":
+        raise _date_filter_error(value, "a range must contain two full dates")
+    try:
+        start = _parse_full_date(raw_start)
+        end = _parse_full_date(raw_end)
+    except ValueError as error:
+        reason = f"range endpoints must be full dates: {error}"
+        raise _date_filter_error(value, reason) from error
+    if start > end:
+        reason = f"range start {start.isoformat()} follows {end.isoformat()}"
+        raise _date_filter_error(value, reason)
+    return ExperimentDateRange(start=start, end=end)
+
+
+def _parse_date_selector(value: str) -> ExperimentDateSelector:
+    """Return one validated year, year-month, month-day, or full date."""
+    match = _YEAR_PATTERN.fullmatch(value)
+    if match is not None:
+        return _validated_selector(value, "year", year=int(match.group(1)))
+
+    match = _YEAR_MONTH_PATTERN.fullmatch(value)
+    if match is not None:
+        return _validated_selector(
+            value,
+            "year_month",
+            year=int(match.group(1)),
+            month=int(match.group(2)),
+        )
+
+    match = _MONTH_DAY_PATTERN.fullmatch(value)
+    if match is not None:
+        return _validated_selector(
+            value,
+            "month_day",
+            month=int(match.group(1)),
+            day=int(match.group(2)),
+        )
+
+    match = _FULL_DATE_PATTERN.fullmatch(value)
+    if match is not None:
+        return _validated_selector(
+            value,
+            "date",
+            year=int(match.group(1)),
+            month=int(match.group(2)),
+            day=int(match.group(3)),
+        )
+    raise _date_filter_error(value, "the selector has an unsupported form")
+
+
+def _parse_full_date(value: str) -> date:
+    """Return one full date or raise a date validation error."""
+    match = _FULL_DATE_PATTERN.fullmatch(value)
+    if match is None:
+        msg = f"{value!r} is not a full date"
+        raise ValueError(msg)
+    year, month, day = (int(part) for part in match.groups())
+    return date(year, month, day)
+
+
+def _validated_selector(
+    source: str,
+    kind: DateSelectorKind,
+    *,
+    year: int | None = None,
+    month: int | None = None,
+    day: int | None = None,
+) -> ExperimentDateSelector:
+    """Build one selector and add source text to validation errors."""
+    try:
+        return ExperimentDateSelector(kind=kind, year=year, month=month, day=day)
+    except ValueError as error:
+        raise _date_filter_error(source, str(error)) from error
+
+
+def _date_filter_error(selector: str, reason: str) -> ValueError:
+    """Return one complete user-facing date filter error."""
+    return ValueError(
+        f"Invalid date selector {selector!r}: {reason}.\n{EXPERIMENT_DATE_FILTER_HELP}"
+    )

{twopy-0.4.0 → twopy-0.4.1}/src/twopy/database/modeled.py

@@ -15,6 +15,12 @@ from pathlib import Path
 from twopy.config import DatabaseAccess
 from twopy.database.catalog import read_database_catalog
 from twopy.database.connection import connect_read_only
+from twopy.database.date_filters import (
+    ExperimentDateFilter,
+    ExperimentDateRange,
+    ExperimentDateSelector,
+    parse_experiment_date_filter,
+)
 from twopy.database.types import DatabaseExperiment, DatabaseValue
 
 __all__ = ["find_recordings", "find_stimulus_presentations"]
@@ -23,10 +29,7 @@ __all__ = ["find_recordings", "find_stimulus_presentations"]
 def find_stimulus_presentations(
     database_dir: Path,
     *,
-    date_year: int | None = None,
-    date_month: int | None = None,
-    date_day: int | None = None,
-    date_contains: str | None = None,
+    date: str | None = None,
     path_contains: str | None = None,
     stimulus_contains: str | None = None,
     genotype_contains: str | None = None,
@@ -42,11 +45,7 @@ def find_stimulus_presentations(
 
     Args:
         database_dir: Folder containing lab SQLite DB files.
-        date_year: Optional four-digit year matched against experiment date.
-        date_month: Optional month number matched against experiment date.
-        date_day: Optional day-of-month matched against experiment date.
-        date_contains: Optional substring matched against full experiment date
-            text.
+        date: Optional date expression with selectors and inclusive ranges.
         path_contains: Optional substring matched against ``relativeDataPath``.
         stimulus_contains: Optional substring matched against ``stimulusFunction``.
         genotype_contains: Optional substring matched against fly ``genotype``.
@@ -73,6 +72,7 @@ def find_stimulus_presentations(
     if limit < 1:
         msg = "Database query limit must be at least 1"
         raise ValueError(msg)
+    date_filter = parse_experiment_date_filter(date)
 
     catalog = read_database_catalog(
         database_dir,
@@ -89,10 +89,7 @@ def find_stimulus_presentations(
 
             rows = _query_stimulus_presentations(
                 connection=connection,
-                date_year=date_year,
-                date_month=date_month,
-                date_day=date_day,
-                date_contains=date_contains,
+                date_filter=date_filter,
                 path_contains=path_contains,
                 stimulus_contains=stimulus_contains,
                 genotype_contains=genotype_contains,
@@ -116,9 +113,7 @@ def find_stimulus_presentations(
 def find_recordings(
     database_dir: Path,
     *,
-    year: int | None = None,
-    month: int | None = None,
-    day: int | None = None,
+    date: str | None = None,
     genotype: str | None = None,
     stimulus: str | None = None,
     sensor: str | None = None,
@@ -133,9 +128,7 @@ def find_recordings(
 
     Args:
         database_dir: Folder containing lab SQLite DB files.
-        year: Optional experiment year.
-        month: Optional experiment month.
-        day: Optional experiment day-of-month.
+        date: Optional date expression with selectors and inclusive ranges.
         genotype: Optional genotype substring.
         stimulus: Optional stimulus-function substring.
         sensor: Optional sensor substring from fly ``fluorescentProtein``.
@@ -158,9 +151,7 @@ def find_recordings(
     """
     return find_stimulus_presentations(
         database_dir,
-        date_year=year,
-        date_month=month,
-        date_day=day,
+        date=date,
         stimulus_contains=stimulus,
         genotype_contains=genotype,
         sensor_contains=sensor,
@@ -199,10 +190,7 @@ def _has_tables(connection: sqlite3.Connection, table_names: tuple[str, ...]) ->
 def _query_stimulus_presentations(
     *,
     connection: sqlite3.Connection,
-    date_year: int | None,
-    date_month: int | None,
-    date_day: int | None,
-    date_contains: str | None,
+    date_filter: ExperimentDateFilter | None,
     path_contains: str | None,
     stimulus_contains: str | None,
     genotype_contains: str | None,
@@ -216,10 +204,7 @@ def _query_stimulus_presentations(
 
     Args:
         connection: Open SQLite connection.
-        date_year: Optional experiment year.
-        date_month: Optional experiment month.
-        date_day: Optional experiment day-of-month.
-        date_contains: Optional substring matched against experiment date.
+        date_filter: Optional explicit date selectors and inclusive ranges.
         path_contains: Optional relative path substring.
         stimulus_contains: Optional stimulus-function substring.
         genotype_contains: Optional genotype substring.
@@ -238,19 +223,16 @@ def _query_stimulus_presentations(
     where_clauses: list[str] = []
     parameters: list[DatabaseValue] = []
 
-    _append_date_filters(
+    _append_date_filter_expression(
         where_clauses=where_clauses,
         parameters=parameters,
-        year=date_year,
-        month=date_month,
-        day=date_day,
+        date_filter=date_filter,
     )
     _append_optional_text_filters(
         where_clauses=where_clauses,
         parameters=parameters,
         filters={
             'CAST(sp."relativeDataPath" AS TEXT) LIKE ?': path_contains,
-            'CAST(sp."date" AS TEXT) LIKE ?': date_contains,
             'CAST(sp."stimulusFunction" AS TEXT) LIKE ?': stimulus_contains,
             'CAST(f."genotype" AS TEXT) LIKE ?': genotype_contains,
             'CAST(f."fluorescentProtein" AS TEXT) LIKE ?': sensor_contains,
@@ -312,6 +294,78 @@ def _append_optional_text_filters(
             parameters.append(f"%{value}%")
 
 
+def _append_date_filter_expression(
+    *,
+    where_clauses: list[str],
+    parameters: list[DatabaseValue],
+    date_filter: ExperimentDateFilter | None,
+) -> None:
+    """Add one grouped date expression to a modeled query.
+
+    Args:
+        where_clauses: SQL where clauses being built.
+        parameters: SQL parameter values being built.
+        date_filter: Validated selectors joined with logical ``OR``.
+
+    Returns:
+        None. The function appends one grouped clause and its parameters.
+
+    All comparisons use the fixed date portion of the stored timestamp. This
+    includes every recording time on an inclusive range end date.
+    """
+    if date_filter is None:
+        return
+
+    item_clauses: list[str] = []
+    for item in date_filter.items:
+        if isinstance(item, ExperimentDateRange):
+            item_clauses.append(
+                '(substr(CAST(sp."date" AS TEXT), 1, 10) BETWEEN ? AND ?)'
+            )
+            parameters.extend((item.start.isoformat(), item.end.isoformat()))
+            continue
+
+        clause, values = _date_selector_condition(item)
+        item_clauses.append(clause)
+        parameters.extend(values)
+    where_clauses.append(f"({' OR '.join(item_clauses)})")
+
+
+def _date_selector_condition(
+    selector: ExperimentDateSelector,
+) -> tuple[str, tuple[str, ...]]:
+    """Return one SQL condition and its bound date values."""
+    if selector.kind == "year":
+        assert selector.year is not None
+        return (
+            '(substr(CAST(sp."date" AS TEXT), 1, 4) = ?)',
+            (f"{selector.year:04d}",),
+        )
+    if selector.kind == "year_month":
+        assert selector.year is not None and selector.month is not None
+        return (
+            "("
+            'substr(CAST(sp."date" AS TEXT), 1, 4) = ? AND '
+            'substr(CAST(sp."date" AS TEXT), 6, 2) = ?'
+            ")",
+            (f"{selector.year:04d}", f"{selector.month:02d}"),
+        )
+    if selector.kind == "month_day":
+        assert selector.month is not None and selector.day is not None
+        return (
+            "("
+            'substr(CAST(sp."date" AS TEXT), 6, 2) = ? AND '
+            'substr(CAST(sp."date" AS TEXT), 9, 2) = ?'
+            ")",
+            (f"{selector.month:02d}", f"{selector.day:02d}"),
+        )
+
+    return (
+        '(substr(CAST(sp."date" AS TEXT), 1, 10) = ?)',
+        (selector.normalized,),
+    )
+
+
 def _experiment_from_row(database_path: Path, row: sqlite3.Row) -> DatabaseExperiment:
     """Convert one joined SQLite row into a typed experiment.
 
@@ -338,65 +392,6 @@ def _experiment_from_row(database_path: Path, row: sqlite3.Row) -> DatabaseExper
     )
 
 
-def _append_date_filters(
-    *,
-    where_clauses: list[str],
-    parameters: list[DatabaseValue],
-    year: int | None,
-    month: int | None,
-    day: int | None,
-) -> None:
-    """Add flexible year, month, and day filters for experiment dates.
-
-    Args:
-        where_clauses: SQL where clauses being built.
-        parameters: SQL parameter values being built.
-        year: Optional experiment year.
-        month: Optional experiment month.
-        day: Optional experiment day-of-month.
-
-    Returns:
-        None. The function appends clauses and parameters in place.
-
-    The lab DB stores dates as ``YYYY-MM-DD HH:MM:SS`` text. ``substr`` keeps the
-    query simple and allows year-only, month-only, day-only, or combined filters.
-    """
-    if year is not None:
-        _validate_range("year", year, 1, 9999)
-        where_clauses.append('substr(CAST(sp."date" AS TEXT), 1, 4) = ?')
-        parameters.append(f"{year:04d}")
-
-    if month is not None:
-        _validate_range("month", month, 1, 12)
-        where_clauses.append('substr(CAST(sp."date" AS TEXT), 6, 2) = ?')
-        parameters.append(f"{month:02d}")
-
-    if day is not None:
-        _validate_range("day", day, 1, 31)
-        where_clauses.append('substr(CAST(sp."date" AS TEXT), 9, 2) = ?')
-        parameters.append(f"{day:02d}")
-
-
-def _validate_range(name: str, value: int, minimum: int, maximum: int) -> None:
-    """Validate one integer filter range.
-
-    Args:
-        name: Filter name for error messages.
-        value: Integer value to check.
-        minimum: Smallest accepted value.
-        maximum: Largest accepted value.
-
-    Returns:
-        None when the value is valid.
-
-    Raises:
-        ValueError: If the value falls outside the accepted range.
-    """
-    if not minimum <= value <= maximum:
-        msg = f"{name} must be between {minimum} and {maximum}. Got {value}"
-        raise ValueError(msg)
-
-
 def _optional_string(value: object) -> str | None:
     """Convert nullable SQLite values into optional strings.