From 5221978c1c7f339eb16c1949d0e2dd401cb7e356 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 | 454 +++++++++--------- src/fmu/dataio/case.py | 4 +- .../datastructure/_internal/internal.py | 6 +- .../configuration/global_configuration.py | 2 +- src/fmu/dataio/datastructure/meta/meta.py | 300 +++++++----- src/fmu/dataio/providers/_fmu.py | 4 +- tests/conftest.py | 2 +- 8 files changed, 430 insertions(+), 346 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..4961764c8 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\nA case represent a set of iterations that belong together, either by being part of\nthe same run (i.e. history matching) or by being placed together by the user,\ncorresponding to /scratch////.\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.\n\nA case represent a set of iterations that belong together, either by being part of\nthe same run (i.e. history matching) or by being placed together by the user,\ncorresponding to /scratch////.", + "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\nresults data model can be applied to data from *other* sources - in which the\nfmu-specific stuff may 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\nresults data model can be applied to data from *other* sources - in which the\nfmu-specific stuff may 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": [ @@ -7357,7 +7354,7 @@ "type": "object" }, "SystemInformationOperatingSystem": { - "description": "This model encapsulates various pieces of\nsystem-related information using Python's platform module. It provides a\nstructured way to access details about the system's hardware, operating\nsystem, and interpreter version information.", + "description": "This model encapsulates various pieces of system-related information using Python's\nplatform module. It provides a structured way to access details about the system's\nhardware, operating system, and interpreter version information.", "properties": { "hostname": { "description": "The network name of the computer, possibly not fully qualified.", @@ -8346,6 +8343,7 @@ "type": "object" }, "TracklogEvent": { + "description": "The ``tracklog`` block contains a record of events recorded on these data.\nThis data object describes a tracklog event.", "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..f45a88bc9 100644 --- a/src/fmu/dataio/datastructure/meta/meta.py +++ b/src/fmu/dataio/datastructure/meta/meta.py @@ -114,57 +114,73 @@ 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. + + A case represent a set of iterations that belong together, either by being part of + the same run (i.e. history matching) or by being placed together by the user, + corresponding to /scratch////. + + .. 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. + See :class:`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. In ERT, custom names for iterations are supported, e.g. "pred".""" + + 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 +202,112 @@ 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. We 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): @@ -259,10 +316,9 @@ class VersionInformation(BaseModel): class SystemInformationOperatingSystem(BaseModel): """ - This model encapsulates various pieces of - system-related information using Python's platform module. It provides a - structured way to access details about the system's hardware, operating - system, and interpreter version information. + This model encapsulates various pieces of system-related information using Python's + platform module. It provides a structured way to access details about the system's + hardware, operating system, and interpreter version information. """ hostname: str = Field( @@ -315,6 +371,10 @@ class SystemInformation(BaseModel): class TracklogEvent(BaseModel): + """The ``tracklog`` block contains a record of events recorded on these data. + This data object describes a tracklog event. + """ + # TODO: Update ex. to inc. timezone # update NaiveDatetime -> AwareDatetime # On upload, sumo adds timezone if its lacking. @@ -341,23 +401,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 +455,52 @@ 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. + + A case represent a set of iterations that belong together, either by being part of + the same run (i.e. history matching) or by being placed together by the user, + corresponding to /scratch////. + """ + 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 +513,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 +530,8 @@ class Root( RootModel[ Annotated[ Union[ - FMUCaseClassMeta, - FMUDataClassMeta, + CaseMetadata, + ObjectMetadata, ], Field(discriminator="class_"), ] @@ -496,9 +582,10 @@ def _remove_discriminator_mapping(obj: Dict) -> Dict: def _remove_format_path(obj: T) -> T: """ - Removes entries with key "format" and value "path" from dictionaries. This adjustment - is necessary because JSON Schema does not recognize the "format": "path", while OpenAPI does. - This function is used in contexts where OpenAPI specifications are not applicable. + Removes entries with key "format" and value "path" from dictionaries. This + adjustment is necessary because JSON Schema does not recognize the "format": + "path", while OpenAPI does. This function is used in contexts where OpenAPI + specifications are not applicable. """ if isinstance(obj, dict): @@ -515,7 +602,6 @@ def _remove_format_path(obj: T) -> T: def dump() -> Dict: - # ruff: noqa: E501 """ Dumps the export root model to JSON format for schema validation and usage in FMU data structures. @@ -530,7 +616,7 @@ def dump() -> Dict: implementations. If changes are satisfactory and do not introduce issues, commit them to maintain schema consistency. - """ + """ # noqa: E501 schema = dict( ChainMap( { 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", ),