PyBIDS 1.0 layout API

Index = PaddedInt
Value = str
Entity = Literal['subject', 'session', ...]

class Schema:
    """Representation of the state of BIDS schema
    
    This replaces the concept of a config file, allowing PyBIDS to accept
    BEP or application-specific schemas.
    
    For the time being, this should be considered opaque to users.
    """

class File:
    """Generic file representation
    
    This permits unparseable filenames to be represented.
    """
    path: Path
    _layout: BIDSLayout | None
    
    # Implement os.PathLike
    def __fspath__(self):
        return str(self.path)
    
    @cached_property
    def relative_path(self) -> Path:
        if not self._layout:
            raise ValueError
        return self.path.relative_to(self._layout.root)

class BIDSFile(File):
    entities: dict[Entity, Value | Index]
    datatype: str | None
    suffix: str | None
    extension: str | None

    @cached_property
    def metadata(self) -> dict[str, Any]:
        """Sidecar metadata aggregated according to inheritance principle"""

class BIDSLayout:
    # Inspired by context: https://github.com/bids-standard/bids-specification/blob/master/src/schema/meta/context.yaml
    schema: Schema
    root: Path
    dataset_description: dict[str, Any]
    # tree: Tree[BIDSFile]  # Probably not

    # Non-conforming files, maybe better name?
    # could be property
    ignored: list[File]

    ## layouts: list[BIDSLayout]
    
    @cached_property
    def files(self) -> list[BIDSFile]: ...
    @cached_property
    def datatypes(self) -> list[str]: ...
    @cached_property
    def modalities(self) -> list[str]: ...
    @cached_property
    def subjects(self) -> list[str]: ...
    @cached_property
    def entities(self) -> list[Entity]: ...
    
    def get_entities(
        self,
        entity: Entity,
        **filters,
    ) -> list[Value | Index]: ...

    def get_metadata(self, term: str, **filters) -> list[Any]: ...
    def get_files(self, **filters) -> list[BIDSFile]: ...

class LayoutCollection(BIDSLayout):
    primary: BIDSLayout
    layouts: list[BIDSLayout]
    
    
mylayout = LayoutCollection('/path/to/ds')
mylayout.primary.entities  # Only once
mylayout.entities  # Iterative

def get_bval(x: BIDSFile) -> BIDSFile: ...
def get_bvec(x: BIDSFile) -> BIDSFile: ...
def get_fieldmap(x: BIDSFile) -> List[BIDSFile]: ...

def parse_file(x: Path | str) -> BIDSFile:
    """Construct a layout-free BIDSFile"""
    
def new_file(
    template: BIDSFile | None = None,
    layout: BIDSLayout | None = None,
    *,
    datatype: str | None = None,
    suffix: str | None = None,
    extension: str | None = None,
    **entities,
) -> BIDSFile:
    """Generate new file
        
    If given a template, additional arguments are overrides.
    """