"""
This type stub file was generated by pyright.
"""
from __future__ import annotations

from functools import lru_cache

""" Model classes used in BIDSLayouts. """
Base = ...

class LayoutInfo(Base):
    """Contains information about a BIDSLayout's initialization parameters."""

    __tablename__ = ...
    root = ...
    absolute_paths = ...
    _derivatives = ...
    _config = ...
    def __init__(self, **kwargs) -> None: ...
    def __repr__(self): ...

class Config(Base):
    """Container for BIDS configuration information.

    Parameters
    ----------
    name : str
        The name to give the Config (e.g., 'bids').
    entities : list
        A list of dictionaries containing entity configuration
        information.
    default_path_patterns : list
        Optional list of patterns used to build new paths.
    session : :obj:`sqlalchemy.orm.session.Session` or None
        An optional SQLAlchemy session. If passed,
        the session is used to update the database with any newly created
        Entity objects. If None, no database update occurs.
    """

    __tablename__ = ...
    name = ...
    _default_path_patterns = ...
    entities: dict[str, Entity] = ...
    def __init__(
        self, name, entities=..., default_path_patterns=..., session=...
    ) -> None: ...
    @classmethod
    def load(self, config: str | dict[str, str], session=...) -> Config:
        """Load a Config instance from the passed configuration data.

        Parameters
        ----------
        config : str or dict
            A string or dict containing configuration information.
            Must be one of:
            * A string giving the name of a predefined config file
                (e.g., 'bids' or 'derivatives')
            * A path to a JSON file containing config information
            * A dictionary containing config information
        session : :obj:`sqlalchemy.orm.session.Session` or None
            An optional SQLAlchemy Session instance.
            If passed, the session is used to check the database for (and
            return) an existing Config with name defined in config['name'].

        Returns
        -------
        A Config instance.
        """
        ...
    def __repr__(self): ...

class BIDSFile(Base):
    """Represents a single file or directory in a BIDS dataset.

    Parameters
    ----------
    filename : str
        The path to the corresponding file.
    """

    __tablename__ = ...
    path: str = ...
    filename = ...
    dirname = ...
    entities: list[Entity] = ...
    is_dir = ...
    class_ = ...
    _associations = ...
    __mapper_args__ = ...
    def __init__(self, filename) -> None: ...
    def __getattr__(self, attr): ...
    def __repr__(self): ...
    def __fspath__(self): ...
    @property
    @lru_cache()
    def relpath(self):  # -> str:
        """Return path relative to layout root"""
        ...
    def get_associations(
        self, kind=..., include_parents=...
    ):  # -> Any | list[Unknown]:
        """Get associated files, optionally limiting by association kind.

        Parameters
        ----------
        kind : str
            The kind of association to return (e.g., "Child").
            By default, all associations are returned.
        include_parents : bool
            If True, files related through inheritance
            are included in the returned list. If False, only directly
            associated files are returned. For example, a file's JSON
            sidecar will always be returned, but other JSON files from
            which the sidecar inherits will only be returned if
            include_parents=True.

        Returns
        -------
        list
            A list of BIDSFile instances.
        """
        ...
    def get_metadata(self):  # -> BIDSMetadata:
        """Return all metadata associated with the current file."""
        ...
    def get_entities(self, metadata=..., values=...):  # -> dict[Unknown, Unknown]:
        """Return entity information for the current file.

        Parameters
        ----------
        metadata : bool or None
            If False (default), only entities defined
            for filenames (and not those found in the JSON sidecar) are
            returned. If True, only entities found in metadata files (and not
            defined for filenames) are returned. If None, all available
            entities are returned.
        values : str
            The kind of object to return in the dict's values.
            Must be one of:
                * 'tags': Returns only the tagged value--e.g., if the key
                is "subject", the value might be "01".
                * 'objects': Returns the corresponding Entity instance.

        Returns
        -------
        dict
            A dict, where keys are entity names and values are Entity
            instances.
        """
        ...
    def copy(
        self, path_patterns, symbolic_link=..., root=..., conflicts=...
    ):  # -> None:
        """Copy the contents of a file to a new location.

        Parameters
        ----------
        path_patterns : list
            List of patterns used to construct the new
            filename. See :obj:`build_path` documentation for details.
        symbolic_link : bool
            If True, use a symbolic link to point to the
            existing file. If False, creates a new file.
        root : str
            Optional path to prepend to the constructed filename.
        conflicts : str
            Defines the desired action when the output path already exists.
            Must be one of:
                'fail': raises an exception
                'skip' does nothing
                'overwrite': overwrites the existing file
                'append': adds  a suffix to each file copy, starting with 1
        """
        ...

class BIDSDataFile(BIDSFile):
    """Represents a single data file in a BIDS dataset.

    Derived from `BIDSFile` and provides additional functionality such as
    obtaining pandas DataFrame data representation (via `get_df`).
    """

    __mapper_args__ = ...
    def get_df(
        self, include_timing=..., adjust_onset=..., enforce_dtypes=..., **pd_args
    ):
        """Return the contents of a tsv file as a pandas DataFrame.

        Parameters
        ----------
        include_timing : bool
            If True, adds an "onset" column to dense
            timeseries files (e.g., *_physio.tsv.gz).
        adjust_onset : bool
            If True, the onset of each sample in a dense
            timeseries file is shifted to reflect the "StartTime" value in
            the JSON sidecar. If False, the first sample starts at 0 secs.
            Ignored if include_timing=False.
        enforce_dtypes : bool
            If True, enforces the data types defined in
            the BIDS spec on core columns (e.g., subject_id and session_id
            must be represented as strings).
        pd_args : dict
            Optional keyword arguments to pass onto pd.read_csv().

        Returns
        -------
        :obj:`pandas.DataFrame`
            A pandas DataFrame.
        """
        ...

class BIDSImageFile(BIDSFile):
    """Represents a single neuroimaging data file in a BIDS dataset.

    Derived from `BIDSFile` and provides additional functionality such as
    obtaining nibabel's image file representation (via `get_image`).
    """

    __mapper_args__ = ...
    def get_image(self, **kwargs):
        """Return the associated image file (if it exists) as a NiBabel object

        Any keyword arguments are passed to ``nibabel.load``.
        """
        ...

class BIDSJSONFile(BIDSFile):
    """Represents a single JSON metadata file in a BIDS dataset.

    Derived from `BIDSFile` and provides additional functionality for reading
    the contents of JSON files as either dicts or strings.
    """

    __mapper_args__ = ...
    def get_dict(self):  # -> dict[Unknown, Unknown]:
        """Return the contents of the current file as a dictionary."""
        ...
    def get_json(self):
        """Return the contents of the current file as a JSON string."""
        ...

class Entity(Base):
    """
    Represents a single entity defined in the JSON config.

    Parameters
    ----------
    name : str
        The name of the entity (e.g., 'subject', 'run', etc.)
    pattern : str
        A regex pattern used to match against file names.
        Must define at least one group, and only the first group is
        kept as the match.
    mandatory : bool
        If True, every File _must_ match this entity.
    directory : str
        Optional pattern defining a directory associated
        with the entity.
    dtype : str
        The optional data type of the Entity values. Must be
        one of 'int', 'float', 'bool', or 'str'. If None, no type
        enforcement will be attempted, which means the dtype of the
        value may be unpredictable.
    """

    __tablename__ = ...
    name = ...
    mandatory = ...
    pattern = ...
    directory = ...
    _dtype = ...
    files = ...
    regex: str = ...
    def __init__(
        self, name, pattern=..., mandatory=..., directory=..., dtype=...
    ) -> None: ...
    def __repr__(self): ...
    def __iter__(self): ...
    def __deepcopy__(self, memo): ...
    def match_file(self, f):  # -> PaddedInt | Any | None:
        """
        Determine whether the passed file matches the Entity.

        Parameters
        ----------
        f : BIDSFile
            The BIDSFile instance to match against.

        Returns
        -------
        the matched value if a match was found, otherwise None.
        """
        ...
    def unique(self):  # -> list[Unknown]:
        """Return all unique values/levels for the current entity."""
        ...
    def count(self, files=...):  # -> int:
        """Return a count of unique values or files.

        Parameters
        ----------
        files : bool
            When True, counts all files mapped to the Entity.
            When False, counts all unique values.

        Returns
        -------
        int
            Count of unique values or files.
        """
        ...

class Tag(Base):
    """Represents an association between a File and an Entity.

    Parameters
    ----------
    file : BIDSFile
        The associated BIDSFile.
    entity : Entity
        The associated Entity.
    value : json-serializable type
        The value to store for this file/entity pair. Must be of type
        str, int, float, bool, or any json-serializable structure.
    dtype : str
        Optional type for the value field. If None, inferred from
        value. If passed, must be one of str, int, float, bool, or json.
        Any other value will be treated as json (and will fail if the
        value can't be serialized to json).
    is_metadata : bool
        Indicates whether or not the Entity is derived
        from JSON sidecars (True) or is a predefined Entity from a
        config (False).
    """

    __tablename__ = ...
    file_path = ...
    entity_name = ...
    _value = ...
    _dtype = ...
    is_metadata = ...
    file = ...
    entity = ...
    def __init__(self, file, entity, value, dtype=..., is_metadata=...) -> None: ...
    def __repr__(self): ...

class FileAssociation(Base):
    __tablename__ = ...
    src = ...
    dst = ...
    kind = ...

config_to_entity_map = ...
