From bb354aaa9005e3b2552015f3fe1f6b77161c4242 Mon Sep 17 00:00:00 2001 From: mferrera Date: Thu, 27 Jun 2024 10:40:03 +0200 Subject: [PATCH] DOC: Add more docstrings with some renaming --- docs/src/datamodel/index.rst | 4 +- schema/definitions/0.8.0/schema/fmu_meta.json | 452 +++++++++--------- src/fmu/dataio/case.py | 4 +- .../datastructure/_internal/internal.py | 6 +- .../configuration/global_configuration.py | 2 +- src/fmu/dataio/datastructure/meta/meta.py | 278 +++++++---- src/fmu/dataio/providers/_fmu.py | 4 +- tests/conftest.py | 2 +- 8 files changed, 416 insertions(+), 336 deletions(-) diff --git a/docs/src/datamodel/index.rst b/docs/src/datamodel/index.rst index 2817d0eee..d7ac8f7a2 100644 --- a/docs/src/datamodel/index.rst +++ b/docs/src/datamodel/index.rst @@ -32,8 +32,8 @@ documentation of these two models can be inspected from here. .. toctree:: :maxdepth: -1 - fmu.dataio.datastructure.meta.meta.FMUDataClassMeta - fmu.dataio.datastructure.meta.meta.FMUCaseClassMeta + ~fmu.dataio.datastructure.meta.meta.ObjectMetadata + ~fmu.dataio.datastructure.meta.meta.CaseMetadata About the data model diff --git a/schema/definitions/0.8.0/schema/fmu_meta.json b/schema/definitions/0.8.0/schema/fmu_meta.json index 0639f324b..2bee47457 100644 --- a/schema/definitions/0.8.0/schema/fmu_meta.json +++ b/schema/definitions/0.8.0/schema/fmu_meta.json @@ -395,6 +395,95 @@ "title": "CPGridSpecification", "type": "object" }, + "Case": { + "description": "The ``fmu.case`` block contains information about the case from which this data\nobject was exported.\n\n.. note:: If an FMU data object is exported outside the case context, this block\n will not be present.", + "properties": { + "description": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Description" + }, + "name": { + "examples": [ + "MyCaseName" + ], + "title": "Name", + "type": "string" + }, + "user": { + "$ref": "#/$defs/User" + }, + "uuid": { + "examples": [ + "15ce3b84-766f-4c93-9050-b154861f9100" + ], + "format": "uuid", + "title": "Uuid", + "type": "string" + } + }, + "required": [ + "name", + "user", + "uuid" + ], + "title": "Case", + "type": "object" + }, + "CaseMetadata": { + "description": "The FMU metadata model for an FMU case.", + "properties": { + "access": { + "$ref": "#/$defs/Access" + }, + "class": { + "const": "case", + "title": "metadata_class" + }, + "fmu": { + "$ref": "#/$defs/FMUCaseAttributes" + }, + "masterdata": { + "$ref": "#/$defs/Masterdata" + }, + "source": { + "const": "fmu", + "title": "Source" + }, + "tracklog": { + "items": { + "$ref": "#/$defs/TracklogEvent" + }, + "title": "Tracklog", + "type": "array" + }, + "version": { + "const": "0.8.0", + "title": "Version" + } + }, + "required": [ + "class", + "masterdata", + "tracklog", + "source", + "version", + "fmu", + "access" + ], + "title": "CaseMetadata", + "type": "object" + }, "Classification": { "enum": [ "asset", @@ -418,6 +507,7 @@ "type": "object" }, "CoordinateSystem": { + "description": "Reference to coordinate system known to SMDA.", "properties": { "identifier": { "examples": [ @@ -443,6 +533,7 @@ "type": "object" }, "CountryItem": { + "description": "Reference to a country known to SMDA.", "properties": { "identifier": { "examples": [ @@ -864,6 +955,7 @@ "type": "object" }, "DiscoveryItem": { + "description": "Reference to a discovery known to SMDA.", "properties": { "short_identifier": { "examples": [ @@ -906,118 +998,7 @@ "title": "Display", "type": "object" }, - "FMUCase": { - "properties": { - "description": { - "anyOf": [ - { - "items": { - "type": "string" - }, - "type": "array" - }, - { - "type": "null" - } - ], - "default": null, - "title": "Description" - }, - "name": { - "description": "The case name", - "examples": [ - "MyCaseName" - ], - "title": "Name", - "type": "string" - }, - "user": { - "allOf": [ - { - "$ref": "#/$defs/User" - } - ], - "description": "The user name used in ERT" - }, - "uuid": { - "examples": [ - "15ce3b84-766f-4c93-9050-b154861f9100" - ], - "format": "uuid", - "title": "Uuid", - "type": "string" - } - }, - "required": [ - "name", - "user", - "uuid" - ], - "title": "FMUCase", - "type": "object" - }, - "FMUCaseClassMeta": { - "properties": { - "access": { - "$ref": "#/$defs/Access" - }, - "class": { - "const": "case", - "title": "Metadata class" - }, - "fmu": { - "$ref": "#/$defs/FMUClassMetaCase" - }, - "masterdata": { - "$ref": "#/$defs/Masterdata" - }, - "source": { - "const": "fmu", - "description": "Data source (FMU)", - "title": "Source" - }, - "tracklog": { - "items": { - "$ref": "#/$defs/TracklogEvent" - }, - "title": "Tracklog", - "type": "array" - }, - "version": { - "const": "0.8.0", - "title": "FMU results metadata version" - } - }, - "required": [ - "class", - "masterdata", - "tracklog", - "source", - "version", - "fmu", - "access" - ], - "title": "FMUCaseClassMeta", - "type": "object" - }, - "FMUClassMetaCase": { - "description": "The FMU block records properties that are specific to FMU", - "properties": { - "case": { - "$ref": "#/$defs/FMUCase" - }, - "model": { - "$ref": "#/$defs/FMUModel" - } - }, - "required": [ - "case", - "model" - ], - "title": "FMUClassMetaCase", - "type": "object" - }, - "FMUClassMetaData": { + "FMUAttributes": { "dependencies": { "aggregation": { "not": { @@ -1034,7 +1015,7 @@ } } }, - "description": "The FMU block records properties that are specific to FMU", + "description": "The ``fmu`` block contains all attributes specific to FMU. The idea is that the FMU results\ndata model can be applied to data from *other* sources - in which the fmu-specific stuff\nmay not make sense or be applicable.", "properties": { "aggregation": { "anyOf": [ @@ -1048,7 +1029,7 @@ "default": null }, "case": { - "$ref": "#/$defs/FMUCase" + "$ref": "#/$defs/Case" }, "context": { "$ref": "#/$defs/Context" @@ -1065,7 +1046,7 @@ "default": null }, "model": { - "$ref": "#/$defs/FMUModel" + "$ref": "#/$defs/Model" }, "realization": { "anyOf": [ @@ -1092,117 +1073,27 @@ }, "required": [ "case", - "context", - "model" + "model", + "context" ], - "title": "FMUClassMetaData", + "title": "FMUAttributes", "type": "object" }, - "FMUDataClassMeta": { + "FMUCaseAttributes": { + "description": "The ``fmu`` block contains all attributes specific to FMU. The idea is that the FMU results\ndata model can be applied to data from *other* sources - in which the fmu-specific stuff\nmay not make sense or be applicable.", "properties": { - "access": { - "$ref": "#/$defs/SsdlAccess" - }, - "class": { - "enum": [ - "surface", - "table", - "cpgrid", - "cpgrid_property", - "polygons", - "cube", - "well", - "points", - "dictionary" - ], - "title": "Metadata class", - "type": "string" - }, - "data": { - "$ref": "#/$defs/AnyContent" - }, - "display": { - "$ref": "#/$defs/Display" - }, - "file": { - "$ref": "#/$defs/File" - }, - "fmu": { - "$ref": "#/$defs/FMUClassMetaData" - }, - "masterdata": { - "$ref": "#/$defs/Masterdata" - }, - "source": { - "const": "fmu", - "description": "Data source (FMU)", - "title": "Source" - }, - "tracklog": { - "items": { - "$ref": "#/$defs/TracklogEvent" - }, - "title": "Tracklog", - "type": "array" - }, - "version": { - "const": "0.8.0", - "title": "FMU results metadata version" - } - }, - "required": [ - "class", - "masterdata", - "tracklog", - "source", - "version", - "fmu", - "access", - "data", - "file", - "display" - ], - "title": "FMUDataClassMeta", - "type": "object" - }, - "FMUModel": { - "properties": { - "description": { - "anyOf": [ - { - "items": { - "type": "string" - }, - "type": "array" - }, - { - "type": "null" - } - ], - "default": null, - "description": "This is a free text description of the model setup", - "title": "Description" - }, - "name": { - "examples": [ - "Drogon" - ], - "title": "Name", - "type": "string" + "case": { + "$ref": "#/$defs/Case" }, - "revision": { - "examples": [ - "21.0.0.dev" - ], - "title": "Revision", - "type": "string" + "model": { + "$ref": "#/$defs/Model" } }, "required": [ - "name", - "revision" + "case", + "model" ], - "title": "FMUModel", + "title": "FMUCaseAttributes", "type": "object" }, "FMUTimeObject": { @@ -2185,6 +2076,7 @@ "type": "object" }, "FieldItem": { + "description": "Reference to a field known to SMDA.", "properties": { "identifier": { "examples": [ @@ -3295,6 +3187,7 @@ "type": "object" }, "Iteration": { + "description": "The ``fmu.iteration`` block contains information about the iteration this data\nobject belongs to.", "properties": { "id": { "anyOf": [ @@ -3306,11 +3199,9 @@ } ], "default": null, - "description": "The internal identification of this iteration, e.g. the iteration number", "title": "Id" }, "name": { - "description": "The convential name of this iteration, e.g. iter-0 or pred", "examples": [ "iter-0" ], @@ -3328,7 +3219,6 @@ } ], "default": null, - "description": "A uuid reference to another iteration that this iteration was restarted from", "examples": [ "15ce3b84-766f-4c93-9050-b154861f9100" ], @@ -3977,6 +3867,7 @@ "type": "object" }, "Masterdata": { + "description": "The ``masterdata`` block contains information related to masterdata.\nCurrently, smda holds the masterdata.", "properties": { "smda": { "$ref": "#/$defs/Smda" @@ -3988,6 +3879,46 @@ "title": "Masterdata", "type": "object" }, + "Model": { + "description": "The ``fmu.model`` block contains information about the model used.\n\n.. note::\n Synonyms for \"model\" in this context are \"template\", \"setup\", etc. The term\n \"model\" is ultra-generic but was chosen before e.g. \"template\" as the latter\n deviates from daily communications and is, if possible, even more generic\n than \"model\".", + "properties": { + "description": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Description" + }, + "name": { + "examples": [ + "Drogon" + ], + "title": "Name", + "type": "string" + }, + "revision": { + "examples": [ + "21.0.0.dev" + ], + "title": "Revision", + "type": "string" + } + }, + "required": [ + "name", + "revision" + ], + "title": "Model", + "type": "object" + }, "NamedAreaContent": { "properties": { "alias": { @@ -4281,6 +4212,73 @@ "title": "NamedAreaContent", "type": "object" }, + "ObjectMetadata": { + "description": "The FMU metadata model for a given data object.", + "properties": { + "access": { + "$ref": "#/$defs/SsdlAccess" + }, + "class": { + "enum": [ + "surface", + "table", + "cpgrid", + "cpgrid_property", + "polygons", + "cube", + "well", + "points", + "dictionary" + ], + "title": "metadata_class", + "type": "string" + }, + "data": { + "$ref": "#/$defs/AnyContent" + }, + "display": { + "$ref": "#/$defs/Display" + }, + "file": { + "$ref": "#/$defs/File" + }, + "fmu": { + "$ref": "#/$defs/FMUAttributes" + }, + "masterdata": { + "$ref": "#/$defs/Masterdata" + }, + "source": { + "const": "fmu", + "title": "Source" + }, + "tracklog": { + "items": { + "$ref": "#/$defs/TracklogEvent" + }, + "title": "Tracklog", + "type": "array" + }, + "version": { + "const": "0.8.0", + "title": "Version" + } + }, + "required": [ + "class", + "masterdata", + "tracklog", + "source", + "version", + "fmu", + "access", + "data", + "file", + "display" + ], + "title": "ObjectMetadata", + "type": "object" + }, "PVTContent": { "properties": { "alias": { @@ -5817,9 +5815,9 @@ "type": "object" }, "Realization": { + "description": "The ``fmu.realization`` block contains information about the realization this\ndata object belongs to.", "properties": { "id": { - "description": "The unique number of this realization as used in FMU", "title": "Id", "type": "integer" }, @@ -5831,11 +5829,9 @@ } ], "default": null, - "description": "Content directly taken from the ERT jobs.json file for this realization", "title": "Jobs" }, "name": { - "description": "The convential name of this iteration, e.g. iter-0 or pred", "examples": [ "iter-0" ], @@ -5851,8 +5847,7 @@ "type": "null" } ], - "default": null, - "description": "Parameters for this realization" + "default": null }, "uuid": { "examples": [ @@ -6843,6 +6838,7 @@ "type": "object" }, "Smda": { + "description": "Block containing SMDA-related attributes.", "properties": { "coordinate_system": { "$ref": "#/$defs/CoordinateSystem" @@ -6928,6 +6924,7 @@ "type": "object" }, "StratigraphicColumn": { + "description": "Reference to stratigraphic column known to SMDA.", "properties": { "identifier": { "examples": [ @@ -8346,6 +8343,7 @@ "type": "object" }, "TracklogEvent": { + "description": "The tracklog block contains a record of events recorded on these data. This is experimental for now.\nThis data object describes a tracklog event.\n\n.. note::\n The \"tracklog\" concept is included but considered heavily experimental for now. The concept of\n data lineage goes far beyond this, and this should not be read as the full lineage of these data.", "properties": { "datetime": { "examples": [ @@ -9327,10 +9325,10 @@ }, "oneOf": [ { - "$ref": "#/$defs/FMUCaseClassMeta" + "$ref": "#/$defs/CaseMetadata" }, { - "$ref": "#/$defs/FMUDataClassMeta" + "$ref": "#/$defs/ObjectMetadata" } ], "then": { diff --git a/src/fmu/dataio/case.py b/src/fmu/dataio/case.py index c75d07b82..900a24768 100644 --- a/src/fmu/dataio/case.py +++ b/src/fmu/dataio/case.py @@ -121,10 +121,10 @@ def generate_metadata(self) -> dict: masterdata=meta.Masterdata.model_validate(self.config["masterdata"]), access=meta.Access.model_validate(self.config["access"]), fmu=internal.FMUModelCase( - model=meta.FMUModel.model_validate( + model=meta.Model.model_validate( self.config["model"], ), - case=meta.FMUCase( + case=meta.Case( name=self.casename, uuid=self._case_uuid(), user=meta.User(id=self.caseuser), diff --git a/src/fmu/dataio/datastructure/_internal/internal.py b/src/fmu/dataio/datastructure/_internal/internal.py index d0e568d7d..2e781e9dd 100644 --- a/src/fmu/dataio/datastructure/_internal/internal.py +++ b/src/fmu/dataio/datastructure/_internal/internal.py @@ -108,8 +108,8 @@ class JsonSchemaMetadata(BaseModel, populate_by_name=True): class FMUModelCase(BaseModel): - model: meta.FMUModel - case: meta.FMUCase + model: meta.Model + case: meta.Case class Context(BaseModel, use_enum_values=True): @@ -137,7 +137,7 @@ class UnsetAnyContent(meta.content.AnyContent): root: UnsetContent # type: ignore -class FMUClassMetaData(meta.FMUClassMetaData): +class FMUClassMetaData(meta.FMUAttributes): # This class is identical to the one used in the schema # exept for more fmu context values beeing allowed internally context: Context # type: ignore diff --git a/src/fmu/dataio/datastructure/configuration/global_configuration.py b/src/fmu/dataio/datastructure/configuration/global_configuration.py index 319303a6b..060e0f1a1 100644 --- a/src/fmu/dataio/datastructure/configuration/global_configuration.py +++ b/src/fmu/dataio/datastructure/configuration/global_configuration.py @@ -122,7 +122,7 @@ class GlobalConfiguration(BaseModel): access: Access masterdata: meta.Masterdata - model: meta.FMUModel + model: meta.Model stratigraphy: Optional[Stratigraphy] = Field( default=None, ) diff --git a/src/fmu/dataio/datastructure/meta/meta.py b/src/fmu/dataio/datastructure/meta/meta.py index 68192b1df..686e25046 100644 --- a/src/fmu/dataio/datastructure/meta/meta.py +++ b/src/fmu/dataio/datastructure/meta/meta.py @@ -114,57 +114,68 @@ class User(BaseModel): ) -class FMUCase(BaseModel): - name: str = Field( - description="The case name", - examples=["MyCaseName"], - ) - user: User = Field( - description="The user name used in ERT", - ) - uuid: UUID = Field( - examples=["15ce3b84-766f-4c93-9050-b154861f9100"], - ) - description: Optional[List[str]] = Field( - default=None, - ) +class Case(BaseModel): + """The ``fmu.case`` block contains information about the case from which this data + object was exported. + + .. note:: If an FMU data object is exported outside the case context, this block + will not be present. + """ + + name: str = Field(examples=["MyCaseName"]) + """The name of the case.""" + + user: User + """A block holding information about the user.""" + + uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"]) + """The unique identifier of this case. Currently made by fmu.dataio.""" + + description: Optional[List[str]] = Field(default=None) + """A free-text description of this case.""" class Iteration(BaseModel): - id: Optional[int] = Field( - default=None, - description=( - "The internal identification of this iteration, e.g. the iteration number" - ), - ) - name: str = Field( - description="The convential name of this iteration, e.g. iter-0 or pred", - examples=["iter-0"], - ) - uuid: UUID = Field( - examples=["15ce3b84-766f-4c93-9050-b154861f9100"], - ) + """The ``fmu.iteration`` block contains information about the iteration this data + object belongs to.""" + + id: Optional[int] = Field(default=None) + """The internal identification of this iteration, typically represented by an + integer.""" + + name: str = Field(examples=["iter-0"]) + """The name of the iteration. This is typically reflecting the folder name on + scratch.""" + + uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"]) + """The unique identifier of this case. Currently made by fmu.dataio.""" + restart_from: Optional[UUID] = Field( default=None, - description=( - "A uuid reference to another iteration that this " - "iteration was restarted from" - ), examples=["15ce3b84-766f-4c93-9050-b154861f9100"], ) + """A uuid reference to another iteration that this iteration was restarted + from""" -class FMUModel(BaseModel): - description: Optional[List[str]] = Field( - default=None, - description="This is a free text description of the model setup", - ) - name: str = Field( - examples=["Drogon"], - ) - revision: str = Field( - examples=["21.0.0.dev"], - ) +class Model(BaseModel): + """The ``fmu.model`` block contains information about the model used. + + .. note:: + Synonyms for "model" in this context are "template", "setup", etc. The term + "model" is ultra-generic but was chosen before e.g. "template" as the latter + deviates from daily communications and is, if possible, even more generic + than "model". + """ + + description: Optional[List[str]] = Field(default=None) + """This is a free text description of the model setup""" + + name: str = Field(examples=["Drogon"]) + """The name of the model.""" + + revision: str = Field(examples=["21.0.0.dev"]) + """The revision of the model.""" class RealizationJobListing(BaseModel): @@ -186,71 +197,113 @@ class RealizationJobListing(BaseModel): class Realization(BaseModel): - id: int = Field( - description="The unique number of this realization as used in FMU", - ) - name: str = Field( - description="The convential name of this iteration, e.g. iter-0 or pred", - examples=["iter-0"], - ) - parameters: Optional[Parameters] = Field( - default=None, - description="Parameters for this realization", - ) - jobs: Optional[object] = Field( - default=None, - description=( - "Content directly taken from the ERT jobs.json file for this realization" - ), - ) + """The ``fmu.realization`` block contains information about the realization this + data object belongs to.""" + + id: int + """The internal ID of the realization, typically represented by an integer.""" + + name: str = Field(examples=["iter-0"]) + """The name of the realization. This is typically reflecting the folder name on + scratch. Custom names for realizations are not supported by ERT, but we still + recommend to use ``fmu.realization.id`` for all usage except purely visual + appearance.""" + + parameters: Optional[Parameters] = Field(default=None) + """These are the parameters used in this realization. It is a direct pass of + ``parameters.txt`` and will contain key:value pairs representing the design + parameters. See :class:`Parameters`.""" + + jobs: Optional[object] = Field(default=None) + """Content directly taken from the ERT jobs.json file for this realization.""" + uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"]) + """The universally unique identifier for this realization. It is a hash of + ``fmu.case.uuid`` and ``fmu.iteration.uuid`` and ``fmu.realization.id``.""" class CountryItem(BaseModel): - identifier: str = Field( - examples=["Norway"], - ) + """Reference to a country known to SMDA.""" + + identifier: str = Field(examples=["Norway"]) + """Identifier known to SMDA.""" + uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"]) + """Identifier known to SMDA.""" class DiscoveryItem(BaseModel): - short_identifier: str = Field( - examples=["SomeDiscovery"], - ) + """Reference to a discovery known to SMDA.""" + + short_identifier: str = Field(examples=["SomeDiscovery"]) + """Identifier known to SMDA.""" + uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"]) + """Identifier known to SMDA.""" class FieldItem(BaseModel): - identifier: str = Field( - examples=["OseFax"], - ) + """Reference to a field known to SMDA.""" + + identifier: str = Field(examples=["OseFax"]) + """Identifier known to SMDA.""" + uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"]) + """Identifier known to SMDA.""" class CoordinateSystem(BaseModel): - identifier: str = Field( - examples=["ST_WGS84_UTM37N_P32637"], - ) + """Reference to coordinate system known to SMDA.""" + + identifier: str = Field(examples=["ST_WGS84_UTM37N_P32637"]) + """Identifier known to SMDA.""" + uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"]) + """Identifier known to SMDA.""" class StratigraphicColumn(BaseModel): - identifier: str = Field( - examples=["DROGON_2020"], - ) + """Reference to stratigraphic column known to SMDA.""" + + identifier: str = Field(examples=["DROGON_2020"]) + """Identifier known to SMDA.""" + uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"]) + """Identifier known to SMDA.""" class Smda(BaseModel): + """Block containing SMDA-related attributes.""" + coordinate_system: CoordinateSystem + """Reference to coordinate system known to SMDA. + See :class:`CoordinateSystem`.""" + country: List[CountryItem] + """A list referring to countries known to SMDA. First item is primary. + See :class:`CountryItem`.""" + discovery: List[DiscoveryItem] + """A list referring to discoveries known to SMDA. First item is primary. + See :class:`DiscoveryItem`.""" + field: List[FieldItem] + """A list referring to fields known to SMDA. First item is primary. + See :class:`FieldItem`.""" + stratigraphic_column: StratigraphicColumn + """Reference to stratigraphic column known to SMDA. + See :class:`StratigraphicColumn`.""" class Masterdata(BaseModel): + """The ``masterdata`` block contains information related to masterdata. + Currently, smda holds the masterdata. + """ + smda: Smda + """Block containing SMDA-related attributes. + See :class:`Smda`.""" class VersionInformation(BaseModel): @@ -315,6 +368,14 @@ class SystemInformation(BaseModel): class TracklogEvent(BaseModel): + """The tracklog block contains a record of events recorded on these data. This is experimental for now. + This data object describes a tracklog event. + + .. note:: + The "tracklog" concept is included but considered heavily experimental for now. The concept of + data lineage goes far beyond this, and this should not be read as the full lineage of these data. + """ + # TODO: Update ex. to inc. timezone # update NaiveDatetime -> AwareDatetime # On upload, sumo adds timezone if its lacking. @@ -341,23 +402,25 @@ class Context(BaseModel): stage: enums.FmuContext -class FMUClassMetaCase(BaseModel): +class FMUCaseAttributes(BaseModel): """ - The FMU block records properties that are specific to FMU + The ``fmu`` block contains all attributes specific to FMU. The idea is that the FMU results + data model can be applied to data from *other* sources - in which the fmu-specific stuff + may not make sense or be applicable. """ - case: FMUCase - model: FMUModel + case: Case + model: Model -class FMUClassMetaData(BaseModel): +class FMUAttributes(FMUCaseAttributes): """ - The FMU block records properties that are specific to FMU + The ``fmu`` block contains all attributes specific to FMU. The idea is that the FMU results + data model can be applied to data from *other* sources - in which the fmu-specific stuff + may not make sense or be applicable. """ - case: FMUCase context: Context - model: FMUModel iteration: Optional[Iteration] = Field(default=None) workflow: Optional[Workflow] = Field(default=None) aggregation: Optional[Aggregation] = Field(default=None) @@ -393,27 +456,47 @@ def __get_pydantic_json_schema__( return json_schema -class ClassMeta(BaseModel): +class MetadataBase(BaseModel): + """Base model for all root metadata models generated.""" + class_: enums.FMUClassEnum = Field( alias="class", - title="Metadata class", + title="metadata_class", ) + masterdata: Masterdata + """The ``masterdata`` block contains information related to masterdata. + See :class:`Masterdata`.""" + tracklog: List[TracklogEvent] - source: Literal["fmu"] = Field(description="Data source (FMU)") - version: Literal["0.8.0"] = Field(title="FMU results metadata version") + """The ``tracklog`` block contains a record of events recorded on these data. + See :class:`TracklogEvent`.""" + + source: Literal["fmu"] + """The source of this data. Defaults to 'fmu'.""" + + version: Literal["0.8.0"] + """The version of the schema that generated this data.""" -class FMUCaseClassMeta(ClassMeta): +class CaseMetadata(MetadataBase): + """The FMU metadata model for an FMU case.""" + class_: Literal[enums.FMUClassEnum.case] = Field( alias="class", - title="Metadata class", + title="metadata_class", ) - fmu: FMUClassMetaCase + + fmu: FMUCaseAttributes + """The ``fmu`` block contains all attributes specific to FMU. + See :class:`FMUCaseAttributes`.""" + access: Access -class FMUDataClassMeta(ClassMeta): +class ObjectMetadata(MetadataBase): + """The FMU metadata model for a given data object.""" + class_: Literal[ enums.FMUClassEnum.surface, enums.FMUClassEnum.table, @@ -426,14 +509,13 @@ class FMUDataClassMeta(ClassMeta): enums.FMUClassEnum.dictionary, ] = Field( alias="class", - title="Metadata class", + title="metadata_class", ) - # The presence of the a feild controlls what kind of - # FMUObj it is. The fmu_discriminator will inspects - # the obj. and returns a tag that tells pydantic - # what model to use. - fmu: FMUClassMetaData + fmu: FMUAttributes + """The ``fmu`` block contains all attributes specific to FMU. + See :class:`FMUAttributes`.""" + access: SsdlAccess data: content.AnyContent file: File @@ -444,8 +526,8 @@ class Root( RootModel[ Annotated[ Union[ - FMUCaseClassMeta, - FMUDataClassMeta, + CaseMetadata, + ObjectMetadata, ], Field(discriminator="class_"), ] diff --git a/src/fmu/dataio/providers/_fmu.py b/src/fmu/dataio/providers/_fmu.py index 73980a3ac..06f30ce2b 100644 --- a/src/fmu/dataio/providers/_fmu.py +++ b/src/fmu/dataio/providers/_fmu.py @@ -302,8 +302,8 @@ def _get_iteration_meta(self, iter_uuid: UUID) -> meta.Iteration: def _get_fmucontext_meta(self) -> internal.Context: return internal.Context(stage=self.fmu_context) - def _get_fmumodel_meta(self) -> meta.FMUModel: - return meta.FMUModel.model_validate(self.model) + def _get_fmumodel_meta(self) -> meta.Model: + return meta.Model.model_validate(self.model) def _get_workflow_meta(self) -> meta.Workflow: assert self.workflow is not None diff --git a/tests/conftest.py b/tests/conftest.py index 11088fe48..938ec0106 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -300,7 +300,7 @@ def fixture_globalconfig1(): ssdl=global_configuration.Ssdl(rep_include=False), classification=global_configuration.enums.Classification.internal, ), - model=global_configuration.meta.FMUModel( + model=global_configuration.meta.Model( name="Test", revision="AUTO", ),