Coverage for klayout_pex/plugin_api/v1/pex25d_importer.py: 100%

1# 

2# -------------------------------------------------------------------------------- 

3# SPDX-FileCopyrightText: 2024-2026 Martin Jan Köhler and Harald Pretl 

4# Johannes Kepler University, Institute for Integrated Circuits. 

5# 

6# This file is part of KPEX 

7# (see https://github.com/iic-jku/klayout-pex). 

8# 

9# This program is free software: you can redistribute it and/or modify 

10# it under the terms of the GNU General Public License as published by 

11# the Free Software Foundation, either version 3 of the License, or 

12# (at your option) any later version. 

13# 

14# This program is distributed in the hope that it will be useful, 

15# but WITHOUT ANY WARRANTY; without even the implied warranty of 

16# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 

17# GNU General Public License for more details. 

18# 

19# You should have received a copy of the GNU General Public License 

20# along with this program. If not, see <http://www.gnu.org/licenses/>. 

21# SPDX-License-Identifier: GPL-3.0-or-later 

22# -------------------------------------------------------------------------------- 

23# 

24 

25"""Version 1 PEX25D importer protocol and its errors.""" 

26 

27from __future__ import annotations 

28 

29from typing import TYPE_CHECKING, Any, Mapping, Optional, Protocol 

30 

31if TYPE_CHECKING: 

32 from klayout_pex_protobuf.kpex.pex25d.pex25d_file_pb2 import PEX25DFile 

33 

34 from ...pex25d.diagnostics import DiagnosticsReport 

35 

36 

37class ImporterError(RuntimeError): 

38 """An external scene description could not be imported as PEX25D.""" 

39 

40 

41class ImporterUnavailable(ImporterError): 

42 """The importer or one of its dependencies is unavailable.""" 

43 

44 

45class PEX25DImporter(Protocol): 

46 """Translate one external scene description into an unresolved PEX25DFile. 

47 

48 Resolution and PEX25D validation belong to the caller. Importers preserve 

49 source references where possible and must report unsupported constructs or 

50 missing physical information rather than inventing values. They do not run 

51 a solver or mutate the supplied options or supporting-file mapping. 

52 """ 

53 

54 def import_file(self, 

55 input_file_path: str, 

56 *, 

57 supporting_files: Optional[Mapping[str, str]] = None, 

58 options: Optional[Mapping[str, Any]] = None, 

59 report: Optional[DiagnosticsReport] = None) -> PEX25DFile: 

60 """Read a primary input and optional named supporting files. 

61 

62 Supporting-file keys are defined by the importer, e.g. ``process_stack``. 

63 Input paths are interpreted relative to the caller's working directory; 

64 the importer must not change it. Each call produces one PEX25DFile, so a 

65 batch of independent patterns remains a batch of separate calls. 

66 

67 Append diagnostics to ``report`` when supplied. Raise ImporterError for 

68 an import that cannot complete; do not return a partial file as success. 

69 NotImplementedError marks what an importer does not implement yet. 

70 Optional dependencies should be imported only when needed. 

71 """ 

72 ... 

73 

74 

75__all__ = ['ImporterError', 'ImporterUnavailable', 'PEX25DImporter']