audex 1.0.7a3__py3-none-any.whl

audex/entity/fields.py

@@ -0,0 +1,401 @@
+# ruff: noqa: N802
+from __future__ import annotations
+
+import datetime
+import typing as t
+
+if t.TYPE_CHECKING:
+    from audex.entity import Entity
+
+
+T = t.TypeVar("T")
+
+
+class FieldSpec(t.Generic[T]):
+    """A descriptor for entity fields with validation and default value
+    support.
+
+    This descriptor provides type-safe field access with optional validation,
+    default values, immutability, and nullable support.
+
+    Attributes:
+        default: The default value for the field.
+        default_factory: A callable that returns the default value.
+        nullable: Whether the field can be None.
+        immutable: Whether the field can be modified after initial assignment.
+        sortable: Whether the field supports sorting operations.
+        name: The public name of the field (set by __set_name__).
+        private_name: The private attribute name for storing the value.
+        _field_type: Stored type information for stub generation.
+
+    Args:
+        default: Default value for the field.
+        default_factory: Callable that returns a default value.
+        nullable: Whether None is allowed as a value.
+        immutable: Whether the field can be modified after being set.
+        sortable: Whether the field supports sorting operations.
+    """
+
+    def __init__(
+        self,
+        *,
+        default: T | None = None,
+        default_factory: t.Callable[[], T] | None = None,
+        nullable: bool = False,
+        immutable: bool = False,
+        sortable: bool = True,
+    ) -> None:
+        self.default = default
+        self.default_factory = default_factory
+        self.nullable = nullable
+        self.immutable = immutable
+        self.sortable = sortable
+        self.name: str = ""
+        self.private_name: str = ""
+        self._field_type: type | None = None  # Store type information
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        """Set the field name when the descriptor is assigned to a class
+        attribute.
+
+        Args:
+            owner: The class that owns this descriptor.
+            name: The name of the attribute.
+        """
+        self.name = name
+        self.private_name = f"_field_{name}"
+
+    @t.overload
+    def __get__(self, obj: None, objtype: type[t.Any] | None = None) -> t.Self: ...
+    @t.overload
+    def __get__(self, obj: Entity, objtype: type[t.Any] | None = None) -> T: ...
+    def __get__(self, obj: Entity | None, objtype: type[t.Any] | None = None) -> T | t.Self:
+        """Get the field value."""
+        if obj is None:
+            return self
+
+        if not hasattr(obj, self.private_name):
+            if self.default_factory is not None:
+                value = self.default_factory()
+            elif self.default is not None:
+                value = self.default
+            elif self.nullable:
+                value = None
+            else:
+                raise AttributeError(f"Field '{self.name}' has not been set")
+            setattr(obj, self.private_name, value)
+
+        return t.cast(T, getattr(obj, self.private_name))
+
+    def __set__(self, obj: Entity, value: T) -> None:
+        """Set the field value."""
+        if hasattr(obj, self.private_name) and self.immutable:
+            raise AttributeError(f"Field '{self.name}' is immutable")
+
+        if value is None and not self.nullable:
+            raise ValueError(f"Field '{self.name}' cannot be None")
+
+        setattr(obj, self.private_name, value)
+
+    def __delete__(self, obj: Entity) -> None:
+        """Delete the field value."""
+        if self.immutable:
+            raise AttributeError(f"Field '{self.name}' is immutable")
+        if hasattr(obj, self.private_name):
+            delattr(obj, self.private_name)
+
+
+# Modified factory functions to store type information
+
+
+class StringBackedFieldSpec(FieldSpec[T]):
+    """A field descriptor for values that are persisted as strings in
+    the database."""
+
+
+@t.overload
+def StringBackedField(
+    _field_type: type[T],
+    *,
+    default: T | None = None,
+    default_factory: t.Callable[[], T] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = True,
+) -> StringBackedFieldSpec[T]: ...
+@t.overload
+def StringBackedField(
+    _field_type: None = None,
+    *,
+    default: t.Any | None = None,
+    default_factory: t.Callable[[], t.Any] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = True,
+) -> StringBackedFieldSpec[t.Any]: ...
+def StringBackedField(
+    _field_type: type[t.Any] | None = None,
+    *,
+    default: t.Any | None = None,
+    default_factory: t.Callable[[], t.Any] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = True,
+) -> t.Any:
+    """Factory function to create a StringBackedFieldSpec."""
+    field = StringBackedFieldSpec(
+        default=default,
+        default_factory=default_factory,
+        nullable=nullable,
+        immutable=immutable,
+        sortable=sortable,
+    )
+    field._field_type = _field_type
+    return field
+
+
+class ListFieldSpec(FieldSpec[list[T]]):
+    """A field descriptor for list/collection values."""
+
+    def __init__(
+        self,
+        *,
+        default: list[T] | None = None,
+        default_factory: t.Callable[[], list[T]] | None = None,
+        nullable: bool = False,
+        immutable: bool = False,
+        sortable: bool = False,
+    ) -> None:
+        super().__init__(
+            default=default,
+            default_factory=default_factory,
+            nullable=nullable,
+            immutable=immutable,
+            sortable=sortable,
+        )
+
+
+@t.overload
+def ListField(
+    _item_type: type[T],
+    *,
+    default: list[T] | None = None,
+    default_factory: t.Callable[[], list[T]] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = False,
+) -> ListFieldSpec[T]: ...
+@t.overload
+def ListField(
+    _item_type: None = None,
+    *,
+    default: list[t.Any] | None = None,
+    default_factory: t.Callable[[], list[t.Any]] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = False,
+) -> ListFieldSpec[t.Any]: ...
+def ListField(
+    _item_type: type[t.Any] | None = None,
+    *,
+    default: list[t.Any] | None = None,
+    default_factory: t.Callable[[], list[t.Any]] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = False,
+) -> ListFieldSpec[t.Any]:
+    """Factory function to create a ListFieldSpec."""
+    field = ListFieldSpec(
+        default=default,
+        default_factory=default_factory,
+        nullable=nullable,
+        immutable=immutable,
+        sortable=sortable,
+    )
+    field._field_type = _item_type
+    return field
+
+
+class ForeignFieldSpec(FieldSpec[T]):
+    """A field descriptor for foreign/complex type values."""
+
+    def __init__(
+        self,
+        *,
+        default: T | None = None,
+        default_factory: t.Callable[[], T] | None = None,
+        nullable: bool = False,
+        immutable: bool = False,
+        sortable: bool = False,
+    ) -> None:
+        super().__init__(
+            default=default,
+            default_factory=default_factory,
+            nullable=nullable,
+            immutable=immutable,
+            sortable=sortable,
+        )
+
+
+@t.overload
+def ForeignField(
+    _field_type: type[T],
+    *,
+    default: T | None = None,
+    default_factory: t.Callable[[], T] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = False,
+) -> ForeignFieldSpec[T]: ...
+@t.overload
+def ForeignField(
+    _field_type: None = None,
+    *,
+    default: t.Any | None = None,
+    default_factory: t.Callable[[], t.Any] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = False,
+) -> ForeignFieldSpec[t.Any]: ...
+def ForeignField(
+    _field_type: type[t.Any] | None = None,
+    *,
+    default: t.Any | None = None,
+    default_factory: t.Callable[[], t.Any] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = False,
+) -> t.Any:
+    """Factory function to create a ForeignFieldSpec."""
+    field = ForeignFieldSpec(
+        default=default,
+        default_factory=default_factory,
+        nullable=nullable,
+        immutable=immutable,
+        sortable=sortable,
+    )
+    field._field_type = _field_type
+    return field
+
+
+# Keep all other field types as they were
+class StringFieldSpec(FieldSpec[str]):
+    """A field descriptor for string values."""
+
+
+def StringField(
+    *,
+    default: str | None = None,
+    default_factory: t.Callable[[], str] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = False,
+) -> t.Any:
+    return StringFieldSpec(
+        default=default,
+        default_factory=default_factory,
+        nullable=nullable,
+        immutable=immutable,
+        sortable=sortable,
+    )
+
+
+class IntegerFieldSpec(FieldSpec[int]):
+    """A field descriptor for integer values."""
+
+
+def IntegerField(
+    *,
+    default: int | None = None,
+    default_factory: t.Callable[[], int] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = True,
+) -> t.Any:
+    return IntegerFieldSpec(
+        default=default,
+        default_factory=default_factory,
+        nullable=nullable,
+        immutable=immutable,
+        sortable=sortable,
+    )
+
+
+class FloatFieldSpec(FieldSpec[float]):
+    """A field descriptor for float values."""
+
+
+def FloatField(
+    *,
+    default: float | None = None,
+    default_factory: t.Callable[[], float] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = True,
+) -> t.Any:
+    return FloatFieldSpec(
+        default=default,
+        default_factory=default_factory,
+        nullable=nullable,
+        immutable=immutable,
+        sortable=sortable,
+    )
+
+
+class BoolFieldSpec(FieldSpec[bool]):
+    """A field descriptor for boolean values."""
+
+
+def BoolField(
+    *,
+    default: bool | None = None,
+    default_factory: t.Callable[[], bool] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = True,
+) -> t.Any:
+    return BoolFieldSpec(
+        default=default,
+        default_factory=default_factory,
+        nullable=nullable,
+        immutable=immutable,
+        sortable=sortable,
+    )
+
+
+class DateTimeFieldSpec(FieldSpec[datetime.datetime]):
+    """A field descriptor for datetime values."""
+
+
+def DateTimeField(
+    *,
+    default: datetime.datetime | None = None,
+    default_factory: t.Callable[[], datetime.datetime] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = True,
+) -> t.Any:
+    return DateTimeFieldSpec(
+        default=default,
+        default_factory=default_factory,
+        nullable=nullable,
+        immutable=immutable,
+        sortable=sortable,
+    )
+
+
+def Field(
+    *,
+    default: t.Any | None = None,
+    default_factory: t.Callable[[], t.Any] | None = None,
+    nullable: bool = False,
+    immutable: bool = False,
+    sortable: bool = False,
+) -> t.Any:
+    return FieldSpec(
+        default=default,
+        default_factory=default_factory,
+        nullable=nullable,
+        immutable=immutable,
+        sortable=sortable,
+    )

audex/entity/segment.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import datetime
+
+from audex import utils
+from audex.entity import BaseEntity
+from audex.entity import touch_after
+from audex.entity.fields import DateTimeField
+from audex.entity.fields import IntegerField
+from audex.entity.fields import StringField
+
+
+class Segment(BaseEntity):
+    """Segment entity representing a continuous audio recording segment.
+
+    Represents one continuous recording segment within a session. Since
+    recording can be stopped and restarted, a session may have multiple
+    segments. Each segment tracks its own timing, audio file location, and
+    sequence order within the session.
+
+    Attributes:
+        id: The unique identifier of the segment. Auto-generated with "segment-"
+            prefix.
+        session_id: The ID of the session this segment belongs to. Foreign key
+            reference to Session entity.
+        sequence: The sequence number of this segment within the session.
+            Starts from 1 and increments for each new segment.
+        audio_key: The audio file key/path in storage. Points to the raw
+            audio recording file.
+        started_at: Timestamp when this segment started recording.
+        ended_at: Timestamp when this segment stopped recording. None if
+            still recording.
+        duration_ms: Duration of the segment in milliseconds. Calculated when
+            recording stops.
+
+    Inherited Attributes:
+        created_at: Timestamp when the segment was created.
+        updated_at: Timestamp when the segment was last updated.
+
+    Example:
+        ```python
+        # Create first segment when starting recording
+        segment = Segment(
+            session_id="session-xyz789",
+            sequence=1,
+            audio_key="audio/session-xyz789/segment-001.wav",
+            started_at=utils.utcnow(),
+        )
+
+        # Stop recording and calculate duration
+        segment.ended_at = utils.utcnow()
+        segment.duration_ms = int(
+            (segment.ended_at - segment.started_at).total_seconds()
+            * 1000
+        )
+        segment.touch()
+
+        # Create second segment when resuming
+        segment2 = Segment(
+            session_id="session-xyz789",
+            sequence=2,
+            audio_key="audio/session-xyz789/segment-002.wav",
+            started_at=utils.utcnow(),
+        )
+        ```
+    """
+
+    id: str = StringField(default_factory=lambda: utils.gen_id(prefix="segment-"))
+    session_id: str = StringField()
+    sequence: int = IntegerField()
+    audio_key: str = StringField()
+    started_at: datetime.datetime = DateTimeField(default_factory=utils.utcnow)
+    ended_at: datetime.datetime | None = DateTimeField(nullable=True)
+    duration_ms: int | None = IntegerField(nullable=True)
+
+    @property
+    def is_recording(self) -> bool:
+        """Check if this segment is currently recording.
+
+        Returns:
+            True if ended_at is None, False otherwise.
+        """
+        return self.ended_at is None
+
+    @touch_after
+    def incr(self) -> None:
+        """Increment the sequence number of this segment by 1.
+
+        Note:
+            The updated_at timestamp is automatically updated.
+        """
+        self.sequence += 1
+
+    @touch_after
+    def decr(self) -> None:
+        """Decrement the sequence number of this segment by 1.
+
+        Note:
+            The updated_at timestamp is automatically updated.
+        """
+        if self.sequence > 1:
+            self.sequence -= 1
+        raise ValueError("Sequence number cannot be less than 1.")
+
+    @touch_after
+    def stop(self) -> None:
+        """Stop the recording of this segment by setting ended_at and
+        calculating duration_ms.
+
+        Note:
+            The updated_at timestamp is automatically updated.
+        """
+        if self.ended_at is None:
+            self.ended_at = utils.utcnow()
+            self.duration_ms = int((self.ended_at - self.started_at).total_seconds() * 1000)

audex/entity/segment.pyi

@@ -0,0 +1,38 @@
+# This file is auto-generated by PrototypeX stub generator.
+# Do not edit manually - changes will be overwritten.
+# Regenerate using: python -m scripts.genstubs gen
+
+from __future__ import annotations
+
+import datetime
+
+from audex.entity import BaseEntity
+
+class Segment(BaseEntity):
+    id: str
+    created_at: datetime.datetime
+    updated_at: datetime.datetime | None
+    session_id: str
+    sequence: int
+    audio_key: str
+    started_at: datetime.datetime
+    ended_at: datetime.datetime | None
+    duration_ms: int | None
+    def __init__(
+        self,
+        *,
+        id: str = ...,
+        created_at: datetime.datetime = ...,
+        updated_at: datetime.datetime | None = None,
+        session_id: str,
+        sequence: int,
+        audio_key: str,
+        started_at: datetime.datetime = ...,
+        ended_at: datetime.datetime | None = None,
+        duration_ms: int | None = None,
+    ) -> None: ...
+    @property
+    def is_recording(self) -> bool: ...
+    def decr(self) -> None: ...
+    def incr(self) -> None: ...
+    def stop(self) -> None: ...

audex/entity/session.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import datetime
+
+from audex import utils
+from audex.entity import BaseEntity
+from audex.entity import touch_after
+from audex.entity.fields import DateTimeField
+from audex.entity.fields import StringBackedField
+from audex.entity.fields import StringField
+from audex.valueobj.session import SessionStatus
+
+
+class Session(BaseEntity):
+    """Session entity representing a doctor-patient conversation
+    session.
+
+    Represents a single recording session where a doctor converses with a
+    patient. A session can be started and stopped multiple times, creating
+    multiple audio segments. Each session belongs to a specific doctor and
+    tracks the overall session status and timing.
+
+    Attributes:
+        id: The unique identifier of the session. Auto-generated with "session-"
+            prefix.
+        doctor_id: The ID of the doctor who owns this session. Foreign key
+            reference to Doctor entity.
+        patient_name: The name of the patient in this session. Optional field
+            for record keeping.
+        clinic_number: Outpatient clinic number. Optional.
+        medical_record_number: Medical record/case number. Optional.
+        diagnosis: Preliminary or final diagnosis. Optional.
+        status: The current status of the session (DRAFT, IN_PROGRESS, COMPLETED,
+            CANCELLED). Defaults to DRAFT.
+        started_at: Timestamp when the session first started recording. None
+            if not yet started.
+        ended_at: Timestamp when the session was completed or cancelled. None
+            if still in progress or draft.
+        notes: Additional notes about the session. Optional field for doctor's
+            remarks.
+
+    Inherited Attributes:
+        created_at: Timestamp when the session was created.
+        updated_at: Timestamp when the session was last updated.
+
+    Example:
+        ```python
+        # Create new session
+        session = Session(
+            doctor_id="doctor-abc123",
+            patient_name="李女士",
+            clinic_number="20250123-001",
+            medical_record_number="MR-2025-001",
+            diagnosis="上呼吸道感染",
+            notes="初诊",
+        )
+
+        # Start recording
+        session.start()
+        print(session.status)  # SessionStatus.IN_PROGRESS
+
+        # Complete session
+        session.complete()
+        print(session.status)  # SessionStatus.COMPLETED
+        ```
+    """
+
+    id: str = StringField(default_factory=lambda: utils.gen_id(prefix="session-"))
+    doctor_id: str = StringField()
+    patient_name: str | None = StringField(nullable=True)
+    clinic_number: str | None = StringField(nullable=True)
+    medical_record_number: str | None = StringField(nullable=True)
+    diagnosis: str | None = StringField(nullable=True)
+    status: SessionStatus = StringBackedField(SessionStatus, default=SessionStatus.DRAFT)
+    started_at: datetime.datetime | None = DateTimeField(nullable=True)
+    ended_at: datetime.datetime | None = DateTimeField(nullable=True)
+    notes: str | None = StringField(nullable=True)
+
+    @property
+    def is_active(self) -> bool:
+        """Check if the session is currently active (in progress).
+
+        Returns:
+            True if status is IN_PROGRESS, False otherwise.
+        """
+        return self.status == SessionStatus.IN_PROGRESS
+
+    @property
+    def is_finished(self) -> bool:
+        """Check if the session is finished (completed or cancelled).
+
+        Returns:
+            True if status is COMPLETED or CANCELLED, False otherwise.
+        """
+        return self.status in (SessionStatus.COMPLETED, SessionStatus.CANCELLED)
+
+    @touch_after
+    def start(self) -> None:
+        """Start the session recording.
+
+        Sets status to IN_PROGRESS and records the start timestamp if this
+        is the first time starting.
+
+        Note:
+            The updated_at timestamp is automatically updated.
+        """
+        if self.status == SessionStatus.DRAFT and self.started_at is None:
+            self.started_at = utils.utcnow()
+        self.status = SessionStatus.IN_PROGRESS
+
+    @touch_after
+    def complete(self) -> None:
+        """Complete the session.
+
+        Sets status to COMPLETED and records the end timestamp.
+
+        Note:
+            The updated_at timestamp is automatically updated.
+        """
+        self.status = SessionStatus.COMPLETED
+        self.ended_at = utils.utcnow()
+
+    @touch_after
+    def cancel(self) -> None:
+        """Cancel the session.
+
+        Sets status to CANCELLED and records the end timestamp.
+
+        Note:
+            The updated_at timestamp is automatically updated.
+        """
+        self.status = SessionStatus.CANCELLED
+        self.ended_at = utils.utcnow()