API Reference / APIリファレンス

The API reference is generated from the Google-style docstrings of the public symbols exported by Wandas. The top-level wandas.__all__ is the primary stable entry surface; module pages expose the corresponding module exports.

WandasのAPIリファレンスは、公開symbolのGoogle style docstringから生成されます。 最上位のwandas.__all__が主要な安定公開面で、各モジュールのページは対応するexportを 公開します。

wandas.inspect(source, *, file_type=None, source_name=None)

Inspect an audio header before constructing a Frame or decoding samples.

This synchronous preflight supports the built-in SoundFile audio reader (WAV, W64, RF64, FLAC, OGG/OGA, Opus, MP3, AIFF/AIF, SND/AU and CAF). It neither constructs a Dask graph nor decodes PCM. CSV, WDF, URL downloads and custom readers are deliberately unsupported: CSV metadata requires parsing the sampled table, while custom readers cannot guarantee header-only inspection. Use read or load for those workflows.

In-memory format inference matches read: explicit file_type, then a stream's .name suffix, then source_name, then anonymous WAV. Local paths use their suffix unless file_type is explicit. A seekable binary stream is inspected from position zero and its original position is restored on success or failure. A borrowed stream is never closed. Local handles opened internally are closed by the reader. This is a snapshot; reading the source later inspects it again and does not reuse this result.

Parameters:

Name	Type	Description	Default
source	str | Path | bytes | bytearray | memoryview | BinaryIO	Local path, bytes-like value, or seekable readable binary stream.	required
file_type	str | None	Optional audio extension, case-insensitive with or without a dot.	None
source_name	str | None	Optional in-memory format hint; never another resource to open.	None

Returns:

Type	Description
dict[str, Any]	A dictionary with samplerate (Hz), channels, frames,
dict[str, Any]	duration (seconds), format, subtype and unit. Values
dict[str, Any]	describe the complete original recording, without channel or time slicing.

Raises:

Type	Description
TypeError	The source type is unsupported or the stream is text.
ValueError	The format is unsupported, a URL is supplied, or a stream cannot be rewound and restored without consuming input.
FileNotFoundError	A local path does not exist.
OSError	A filesystem operation fails for an inaccessible local source.
RuntimeError	SoundFile raises LibsndfileError for corrupt or unsupported audio; the exception propagates without wrapping.

Examples:

>>> import wandas as wd
>>> info = wd.inspect("recording.wav")
>>> if info["channels"] <= 8 and info["duration"] <= 180:
...     recording = wd.read("recording.wav")

Source code in wandas/io/inspect.py

def inspect(
    source: str | Path | bytes | bytearray | memoryview | BinaryIO,
    *,
    file_type: str | None = None,
    source_name: str | None = None,
) -> dict[str, Any]:
    """Inspect an audio header before constructing a Frame or decoding samples.

    This synchronous preflight supports the built-in SoundFile audio reader
    (WAV, W64, RF64, FLAC, OGG/OGA, Opus, MP3, AIFF/AIF, SND/AU and CAF). It neither constructs a Dask graph nor
    decodes PCM. CSV, WDF, URL downloads and custom readers are deliberately
    unsupported: CSV metadata requires parsing the sampled table, while custom
    readers cannot guarantee header-only inspection. Use ``read`` or ``load``
    for those workflows.

    In-memory format inference matches ``read``: explicit ``file_type``, then
    a stream's ``.name`` suffix, then ``source_name``, then anonymous WAV.
    Local paths use their suffix unless ``file_type`` is explicit. A seekable
    binary stream is inspected from position zero and its original position is
    restored on success or failure. A borrowed stream is never closed. Local
    handles opened internally are closed by the reader. This is a snapshot;
    reading the source later inspects it again and does not reuse this result.

    Args:
        source: Local path, bytes-like value, or seekable readable binary stream.
        file_type: Optional audio extension, case-insensitive with or without a dot.
        source_name: Optional in-memory format hint; never another resource to open.

    Returns:
        A dictionary with ``samplerate`` (Hz), ``channels``, ``frames``,
        ``duration`` (seconds), ``format``, ``subtype`` and ``unit``. Values
        describe the complete original recording, without channel or time slicing.

    Raises:
        TypeError: The source type is unsupported or the stream is text.
        ValueError: The format is unsupported, a URL is supplied, or a stream
            cannot be rewound and restored without consuming input.
        FileNotFoundError: A local path does not exist.
        OSError: A filesystem operation fails for an inaccessible local source.
        RuntimeError: SoundFile raises ``LibsndfileError`` for corrupt or
            unsupported audio; the exception propagates without wrapping.

    Examples:
        >>> import wandas as wd
        >>> info = wd.inspect("recording.wav")
        >>> if info["channels"] <= 8 and info["duration"] <= 180:
        ...     recording = wd.read("recording.wav")
    """
    if isinstance(source, io.TextIOBase):
        raise TypeError("inspect requires a binary stream, not a text stream")
    if isinstance(source, (str, Path)):
        if "://" in str(source):
            raise ValueError("inspect accepts local audio sources, not URL downloads")
        if not Path(source).exists():
            raise FileNotFoundError(source)
    elif not isinstance(source, (bytes, bytearray, memoryview)) and not _is_file_like(source):
        raise TypeError("inspect requires a local path, bytes or a seekable binary stream")
    selected_type = _infer_in_memory_file_type(source, file_type, source_name)
    reader = get_file_reader(source, file_type=selected_type)
    if type(reader) is not SoundFileReader:
        raise ValueError("inspect supports built-in audio headers only; use read() for CSV or custom readers")
    if not _is_file_like(source):
        return reader.get_file_info(source)
    stream = cast(BinaryIO, source)
    try:
        if not stream.seekable():
            raise ValueError("stream is not seekable")
        position = stream.tell()
        stream.seek(position)
    except (AttributeError, OSError, ValueError) as error:
        raise ValueError("inspect requires a seekable binary stream with a restorable position") from error
    try:
        try:
            stream.seek(0)
        except (OSError, ValueError) as error:
            raise ValueError("inspect requires a seekable binary stream that can rewind to position zero") from error
        return reader.get_file_info(stream)
    finally:
        stream.seek(position)

wandas.from_files(paths, *, base_dir=None, dtype=None)

Create a lazy recording collection from ordered local file paths.

No folder scan, header read, or sample decode occurs during construction. Duplicates remain separate items. Sources must remain available through deferred computation. Sampled-signal CSV sources parse the full table on item access for metadata and again at materialization; failures in the first pass cache None. See ChannelFrameDataset.from_files for the contract.

Parameters:

Name	Type	Description	Default
paths	Iterable[str | Path]	Finite iterable of local strings or Paths.	required
base_dir	str | Path | None	Relative path base; defaults to the construction-time directory.	None
dtype	DTypeLike | None	"float32" or "float64" for every item; None uses :func:get_default_dtype at construction.	None

Returns:

Type	Description
ChannelFrameDataset	ChannelFrameDataset preserving input order and duplicate paths.

Raises:

Type	Description
TypeError	Input is not a collection of local paths.
ValueError	Empty, null-containing, or URL paths are supplied.

Source code in wandas/__init__.py

def from_files(
    paths: Iterable[str | Path],
    *,
    base_dir: str | Path | None = None,
    dtype: "npt.DTypeLike | None" = None,
) -> "ChannelFrameDataset":
    """Create a lazy recording collection from ordered local file paths.

    No folder scan, header read, or sample decode occurs during construction.
    Duplicates remain separate items. Sources must remain available through
    deferred computation. Sampled-signal CSV sources parse the full table on
    item access for metadata and again at materialization; failures in the first
    pass cache ``None``. See ``ChannelFrameDataset.from_files`` for the contract.

    Args:
        paths: Finite iterable of local strings or Paths.
        base_dir: Relative path base; defaults to the construction-time directory.
        dtype: ``"float32"`` or ``"float64"`` for every item; ``None`` uses
            :func:`get_default_dtype` at construction.

    Returns:
        ChannelFrameDataset preserving input order and duplicate paths.

    Raises:
        TypeError: Input is not a collection of local paths.
        ValueError: Empty, null-containing, or URL paths are supplied.
    """
    from .utils.frame_dataset import ChannelFrameDataset

    return ChannelFrameDataset.from_files(paths, base_dir=base_dir, dtype=dtype)

wandas.from_table(table, *, path_column, base_dir=None, metadata_columns=None, dtype=None)

Create a lazy recording collection from a DataFrame or CSV catalog.

Each row remains an independent observation. CSV metadata remains strings; DataFrame basic scalar types are retained and missing values become None. This reads a recording catalog, not the sampled-signal CSV used by read. If a source item is itself a signal CSV, item access parses its full table for metadata; the Dask sample graph parses it again on materialization. See ChannelFrameDataset.from_table for validation and source-lifetime rules.

Parameters:

Name	Type	Description	Default
table	DataFrame | str | Path	pandas DataFrame or local UTF-8/BOM comma-separated CSV catalog.	required
path_column	str	Explicit audio-location column; never inferred.	required
base_dir	str | Path | None	Audio path base; defaults to CSV parent or DataFrame call-time cwd.	None
metadata_columns	Sequence[str] | None	Included metadata columns; defaults to all except path_column.	None
dtype	DTypeLike | None	"float32" or "float64" for every item; None uses :func:get_default_dtype at construction.	None

Returns:

Type	Description
ChannelFrameDataset	ChannelFrameDataset preserving row order, duplicates, and metadata snapshots.

Raises:

Type	Description
TypeError	Unsupported table, source cell, or selected metadata type.
ValueError	Invalid schema, paths, or selected metadata values.
OSError	The CSV catalog cannot be read.
UnicodeError	The CSV catalog is not valid UTF-8.

Source code in wandas/__init__.py

def from_table(
    table: "pd.DataFrame | str | Path",
    *,
    path_column: str,
    base_dir: str | Path | None = None,
    metadata_columns: Sequence[str] | None = None,
    dtype: "npt.DTypeLike | None" = None,
) -> "ChannelFrameDataset":
    """Create a lazy recording collection from a DataFrame or CSV catalog.

    Each row remains an independent observation. CSV metadata remains strings;
    DataFrame basic scalar types are retained and missing values become ``None``.
    This reads a recording catalog, not the sampled-signal CSV used by ``read``.
    If a source item is itself a signal CSV, item access parses its full table for
    metadata; the Dask sample graph parses it again on materialization.
    See ``ChannelFrameDataset.from_table`` for validation and source-lifetime rules.

    Args:
        table: pandas DataFrame or local UTF-8/BOM comma-separated CSV catalog.
        path_column: Explicit audio-location column; never inferred.
        base_dir: Audio path base; defaults to CSV parent or DataFrame call-time cwd.
        metadata_columns: Included metadata columns; defaults to all except path_column.
        dtype: ``"float32"`` or ``"float64"`` for every item; ``None`` uses
            :func:`get_default_dtype` at construction.

    Returns:
        ChannelFrameDataset preserving row order, duplicates, and metadata snapshots.

    Raises:
        TypeError: Unsupported table, source cell, or selected metadata type.
        ValueError: Invalid schema, paths, or selected metadata values.
        OSError: The CSV catalog cannot be read.
        UnicodeError: The CSV catalog is not valid UTF-8.
    """
    from .utils.frame_dataset import ChannelFrameDataset

    return ChannelFrameDataset.from_table(
        table, path_column=path_column, base_dir=base_dir, metadata_columns=metadata_columns, dtype=dtype
    )

wandas.supported_formats()

Return file extensions supported by the registered readers.

Source code in wandas/__init__.py

def supported_formats() -> list[str]:
    """Return file extensions supported by the registered readers."""
    from .io.readers import supported_formats as _supported_formats

    return _supported_formats()

wandas.get_default_dtype()

Return the dtype Wandas uses for data it reads or generates.

Returns:

Type	Description
dtype[Any]	float64 unless changed with :func:set_default_dtype or
dtype[Any]	func:default_dtype.

Source code in wandas/core/default_dtype.py

def get_default_dtype() -> np.dtype[Any]:
    """Return the dtype Wandas uses for data it reads or generates.

    Returns:
        ``float64`` unless changed with :func:`set_default_dtype` or
        :func:`default_dtype`.
    """
    return _default

wandas.set_default_dtype(dtype)

Set the dtype Wandas uses for data it reads or generates.

The setting applies to :func:wandas.read, :meth:ChannelFrame.from_file, the dataset loaders and :func:wandas.generate_sin when they are called without dtype. It is process-wide and not stored in Recipes or WDF files. A dataset keeps the value in effect when it is created, and :meth:RecipePlan.apply_files sends the value in effect when it is called to its worker processes.

Parameters:

Name	Type	Description	Default
dtype	DTypeLike	"float32" or "float64" (or the matching NumPy dtype).	required

Raises:

Type	Description
ValueError	If dtype is not float32 or float64.

Source code in wandas/core/default_dtype.py

def set_default_dtype(dtype: npt.DTypeLike) -> None:
    """Set the dtype Wandas uses for data it reads or generates.

    The setting applies to :func:`wandas.read`, :meth:`ChannelFrame.from_file`,
    the dataset loaders and :func:`wandas.generate_sin` when they are called
    without ``dtype``. It is process-wide and not stored in Recipes or WDF files.
    A dataset keeps the value in effect when it is created, and
    :meth:`RecipePlan.apply_files` sends the value in effect when it is called
    to its worker processes.

    Args:
        dtype: ``"float32"`` or ``"float64"`` (or the matching NumPy dtype).

    Raises:
        ValueError: If ``dtype`` is not float32 or float64.
    """
    global _default
    _default = _normalized(dtype)

wandas.default_dtype(dtype)

Use dtype as the default inside a with block, then restore the previous one.

Parameters:

Name	Type	Description	Default
dtype	DTypeLike	"float32" or "float64" (or the matching NumPy dtype).	required

Raises:

Type	Description
ValueError	If dtype is not float32 or float64.

Source code in wandas/core/default_dtype.py

@contextmanager
def default_dtype(dtype: npt.DTypeLike) -> Iterator[None]:
    """Use ``dtype`` as the default inside a ``with`` block, then restore the previous one.

    Args:
        dtype: ``"float32"`` or ``"float64"`` (or the matching NumPy dtype).

    Raises:
        ValueError: If ``dtype`` is not float32 or float64.
    """
    global _default
    previous = _default
    _default = _normalized(dtype)
    try:
        yield
    finally:
        _default = previous

The tutorials and how-to guides cover workflows that combine several APIs. The learning path is for executable, task-oriented examples.