72 lines
2.6 KiB
Python
72 lines
2.6 KiB
Python
"""Optional capabilities implemented by lazy and borrowing libraries."""
|
|
from __future__ import annotations
|
|
|
|
from abc import ABC, abstractmethod
|
|
from typing import TYPE_CHECKING
|
|
|
|
if TYPE_CHECKING:
|
|
from collections.abc import Sequence
|
|
|
|
from ..pattern import Pattern
|
|
from .base import ILibraryView
|
|
from .mapping import LibraryView
|
|
|
|
|
|
class IMaterializable(ABC):
|
|
"""Capability for libraries which support explicit pattern materialization."""
|
|
|
|
@abstractmethod
|
|
def materialize(self, name: str, *, persist: bool = True) -> Pattern:
|
|
"""Materialize one pattern, optionally retaining it in the library's cache."""
|
|
|
|
def materialize_many(
|
|
self,
|
|
names: Sequence[str],
|
|
*,
|
|
persist: bool = True,
|
|
) -> LibraryView:
|
|
"""Materialize a de-duplicated sequence into a plain read-only view."""
|
|
from .mapping import LibraryView # noqa: PLC0415
|
|
|
|
return LibraryView({
|
|
name: self.materialize(name, persist=persist)
|
|
for name in dict.fromkeys(names)
|
|
})
|
|
|
|
def materialize_detached(self, name: str) -> Pattern:
|
|
"""Materialize a caller-owned pattern which is safe to mutate."""
|
|
return self.materialize(name, persist=False).deepcopy()
|
|
|
|
def materialize_many_detached(
|
|
self,
|
|
names: Sequence[str],
|
|
) -> LibraryView:
|
|
"""Materialize caller-owned patterns without retaining them in this library."""
|
|
from .mapping import LibraryView # noqa: PLC0415
|
|
|
|
materialized = self.materialize_many(names, persist=False)
|
|
return LibraryView({
|
|
name: materialized[name].deepcopy()
|
|
for name in dict.fromkeys(names)
|
|
})
|
|
|
|
|
|
class IBorrowing(ABC):
|
|
"""Capability for library views which directly borrow other libraries."""
|
|
|
|
@abstractmethod
|
|
def borrowed_sources(self) -> tuple[ILibraryView, ...]:
|
|
"""Return the source views directly borrowed by this library."""
|
|
|
|
def source_cell(self, name: str) -> tuple[ILibraryView, str] | None: # noqa: ARG002
|
|
"""
|
|
Return a direct source cell with unchanged layout data, if available.
|
|
|
|
The source may use a different name, which is returned alongside it.
|
|
Port metadata may differ because ports are not layout-file content.
|
|
The result is not recursively resolved: consumers must follow further
|
|
borrowing views themselves and enforce format-specific constraints such
|
|
as whether the visible and source names must match. `None` means the
|
|
source cannot be reused safely or no source provenance is available.
|
|
"""
|
|
return None
|