Skip to content

input4mips_validation.cvs.source_id#

Sub-package Description
values Source ID values definition

input4mips_validation.cvs.source_id #

Source ID CV handling

For validation, see validation.

SOURCE_ID_FILENAME: str = 'input4MIPs_source_id.json' module-attribute #

Default name of the file in which the source ID CV is saved

SourceIDEntriesUnstructured: TypeAlias = dict[str, dict[str, str]] module-attribute #

Form into which source ID entries are serialised for the CVs

SourceIDEntries #

Helper container for handling source ID entries

Source code in src/input4mips_validation/cvs/source_id/__init__.py 
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
@define
class SourceIDEntries:
    """
    Helper container for handling source ID entries
    """

    entries: tuple[SourceIDEntry, ...] = field()
    """Source ID entries"""

    # Note: we are ok with the duplicate validation logic here,
    # because it makes implementation of our helper dunder methods
    # simpler if we can assume that the source IDs are unique.
    @entries.validator
    def _entry_source_ids_are_unique(
        self, attribute: attr.Attribute[Any], value: tuple[SourceIDEntry, ...]
    ) -> None:
        source_ids = self.source_ids
        if len(source_ids) != len(set(source_ids)):
            raise NonUniqueError(
                description=(
                    "The source_id's of the entries in `entries` are not unique"
                ),
                values=source_ids,
            )

    def __getitem__(self, key: str) -> SourceIDEntry:
        """
        Get [`SourceIDEntry`][input4mips_validation.cvs.source_id.SourceIDEntry] by its name

        We return the [`SourceIDEntry`][input4mips_validation.cvs.source_id.SourceIDEntry]
        whose source_id matches `key`.
        """  # noqa: E501
        matching = [v for v in self.entries if v.source_id == key]
        if not matching:
            msg = f"{key!r}. {self.source_ids=!r}"
            raise KeyError(msg)

        if len(matching) > 1:  # pragma: no cover
            msg = "`source_id`'s should be validated as being unique at initialisation"
            raise AssertionError(msg)

        return matching[0]

    def __iter__(self) -> Iterable[SourceIDEntry]:
        """
        Iterate over `self.entries`
        """
        yield from self.entries

    def __len__(self) -> int:
        """
        Get length of `self.entries`
        """
        return len(self.entries)

    @property
    def source_ids(self) -> tuple[str, ...]:
        """
        Source IDs found in the list of entries

        Returns
        -------
            The `source_id`'s found in the list of entries
        """
        return tuple(v.source_id for v in self.entries)

entries: tuple[SourceIDEntry, ...] = field() class-attribute instance-attribute #

Source ID entries

source_ids: tuple[str, ...] property #

Source IDs found in the list of entries

Returns:

Type Description
The `source_id`'s found in the list of entries

__getitem__(key) #

Get SourceIDEntry by its name

We return the SourceIDEntry whose source_id matches key.

Source code in src/input4mips_validation/cvs/source_id/__init__.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def __getitem__(self, key: str) -> SourceIDEntry:
    """
    Get [`SourceIDEntry`][input4mips_validation.cvs.source_id.SourceIDEntry] by its name

    We return the [`SourceIDEntry`][input4mips_validation.cvs.source_id.SourceIDEntry]
    whose source_id matches `key`.
    """  # noqa: E501
    matching = [v for v in self.entries if v.source_id == key]
    if not matching:
        msg = f"{key!r}. {self.source_ids=!r}"
        raise KeyError(msg)

    if len(matching) > 1:  # pragma: no cover
        msg = "`source_id`'s should be validated as being unique at initialisation"
        raise AssertionError(msg)

    return matching[0]

__iter__() #

Iterate over self.entries

Source code in src/input4mips_validation/cvs/source_id/__init__.py 
94
95
96
97
98
def __iter__(self) -> Iterable[SourceIDEntry]:
    """
    Iterate over `self.entries`
    """
    yield from self.entries

__len__() #

Get length of self.entries

Source code in src/input4mips_validation/cvs/source_id/__init__.py 
100
101
102
103
104
def __len__(self) -> int:
    """
    Get length of `self.entries`
    """
    return len(self.entries)

SourceIDEntry #

A single source ID entry

Source code in src/input4mips_validation/cvs/source_id/__init__.py 
38
39
40
41
42
43
44
45
46
47
48
@define
class SourceIDEntry:
    """
    A single source ID entry
    """

    source_id: str
    """The unique value which identifies this source ID"""

    values: SourceIDValues
    """The values defined by this source ID"""

source_id: str instance-attribute #

The unique value which identifies this source ID

values: SourceIDValues instance-attribute #

The values defined by this source ID

SourceIDValues #

Values defined by a source ID

Source code in src/input4mips_validation/cvs/source_id/values.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@frozen
class SourceIDValues:
    """
    Values defined by a source ID
    """

    contact: str
    """Email addresses to contact in case of questions about the file"""

    further_info_url: str
    """URL where further information about the file/data in the file can be found"""

    institution_id: str
    """ID of the institute that created the file"""

    mip_era: str
    """The MIP era to which this file belong"""

    source_version: str
    """The version of the file, as defined by the source"""

    license_id: Union[str, None] = None
    """ID of the license that applies to this dataset"""

    authors: Union[tuple[Author, ...], None] = None
    """Author(s) of the dataset"""

authors: Union[tuple[Author, ...], None] = None class-attribute instance-attribute #

Author(s) of the dataset

contact: str instance-attribute #

Email addresses to contact in case of questions about the file

further_info_url: str instance-attribute #

URL where further information about the file/data in the file can be found

institution_id: str instance-attribute #

ID of the institute that created the file

license_id: Union[str, None] = None class-attribute instance-attribute #

ID of the license that applies to this dataset

mip_era: str instance-attribute #

The MIP era to which this file belong

source_version: str instance-attribute #

The version of the file, as defined by the source

convert_source_id_entries_to_unstructured_cv(source_id_entries) #

Convert SourceIDEntries to the raw CV form

Parameters:

Name Type Description Default
source_id_entries SourceIDEntries

Source ID entries

 required

Returns:

Type Description
Raw CV data
Source code in src/input4mips_validation/cvs/source_id/__init__.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def convert_source_id_entries_to_unstructured_cv(
    source_id_entries: SourceIDEntries,
) -> SourceIDEntriesUnstructured:
    """
    Convert [`SourceIDEntries`][input4mips_validation.cvs.source_id.SourceIDEntries] to the raw CV form

    Parameters
    ----------
    source_id_entries
        Source ID entries

    Returns
    -------
        Raw CV data
    """  # noqa: E501
    unstructured = converter_json.unstructure(source_id_entries)

    raw_cv_form = {
        entry["source_id"]: entry["values"] for entry in unstructured["entries"]
    }

    return raw_cv_form

convert_unstructured_cv_to_source_id_entries(unstructured) #

Convert the raw CV data to a SourceIDEntries

Parameters:

Name Type Description Default
unstructured SourceIDEntriesUnstructured

Unstructured CV data

 required

Returns:

Type Description
Source ID entries
Source code in src/input4mips_validation/cvs/source_id/__init__.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def convert_unstructured_cv_to_source_id_entries(
    unstructured: SourceIDEntriesUnstructured,
) -> SourceIDEntries:
    """
    Convert the raw CV data to a [`SourceIDEntries`][input4mips_validation.cvs.source_id.SourceIDEntries]

    Parameters
    ----------
    unstructured
        Unstructured CV data

    Returns
    -------
        Source ID entries
    """  # noqa: E501
    restructured = {
        "entries": [
            dict(source_id=key, values=value) for key, value in unstructured.items()
        ]
    }

    return converter_json.structure(restructured, SourceIDEntries)

load_source_id_entries(raw_cvs_loader, filename=SOURCE_ID_FILENAME) #

Load the source_id entries in the CVs

Parameters:

Name Type Description Default
raw_cvs_loader RawCVLoader

Loader of raw CVs data.

 required
filename str

Name of the file from which to load the CVs.

Passed to raw_cvs_loader.load_raw.

 SOURCE_ID_FILENAME

Returns:

Type Description
Loaded source ID entries
Source code in src/input4mips_validation/cvs/source_id/__init__.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
def load_source_id_entries(
    raw_cvs_loader: RawCVLoader,
    filename: str = SOURCE_ID_FILENAME,
) -> SourceIDEntries:
    """
    Load the source_id entries in the CVs

    Parameters
    ----------
    raw_cvs_loader
        Loader of raw CVs data.

    filename
        Name of the file from which to load the CVs.

        Passed to
        [`raw_cvs_loader.load_raw`][input4mips_validation.cvs.loading_raw.RawCVLoader.load_raw].

    Returns
    -------
        Loaded source ID entries
    """
    return convert_unstructured_cv_to_source_id_entries(
        json.loads(raw_cvs_loader.load_raw(filename=filename))
    )