dapla-toolbelt-metadata 0.4.2__py3-none-any.whl → 0.6.0__py3-none-any.whl

dapla_metadata/variable_definitions/resources/vardef_model_descriptions_nb.yaml

@@ -0,0 +1,63 @@
+# --- Variabel definisjoner ---
+# ref: https://statistics-norway.atlassian.net/wiki/spaces/MPD/pages/3009839199/VarDef+-+Krav+til+dokumentasjon+av+variabler
+name: |
+  Variabelens navn. Dette skal ikke være en mer “teknisk” forkortelse, men et navn som er forståelig for mennesker, f.eks. “Lønnsinntekter”.
+short_name: |
+  Dette er variabelens kortnavn, som kan være en mer “teknisk” forkortelse, f.eks. wlonn (kortnavnet til Lønnsinntekter). Kortnavnet til en variabel i Vardef skal være unikt.
+  Kravet til kortnavnet er at det kan inneholde a-z (kun små bokstaver), 0-9 og _ (understrek). Minimumslengden på kortnavnet er 2 tegn.  Bokstavene “æ”, “ø” og “å” kan ikke brukes. Disse anbefales erstattet med hhv. “ae”, “oe” og “aa"
+definition: |
+  En definisjon skal beskrive hva variabelen betyr og være så kort og presis som mulig. Mer utfyllende opplysninger kan legges i Merknad-feltet.
+classification_reference: |
+  Lenke (URI) til kodeverk (klassifikasjon eller kodeliste) i KLASS som beskriver verdiene variabelen kan anta. F.eks. vil variabelen “Sivilstand” ha kodeverks-URI Standard for [sivilstand](https://www.ssb.no/klass/klassifikasjoner/19).
+unit_types: |
+  Enhetstype(r) - enheten(e) som beskrives av denne variabelen. Variabelen “sivilstand” vil f.eks. ha enhetstypen person, mens f.eks. “Produsentpris for tjenester” vil ha både foretak og bedrift som enhetstyper siden variabelen kan beskrive begge.
+  ref: https://www.ssb.no/klass/klassifikasjoner/702.
+subject_fields: |
+  Statistikkområde(r) som variabelen brukes innenfor, hentet fra [Kodeliste for statistikkområder i Statistikkbanken](https://www.ssb.no/klass/klassifikasjoner/618).
+  F.eks. tilhører variabelen “Sivilstand” statistikkområdet “Befolkning”.
+contains_special_categories_of_personal_data: |
+  Viser om variabelen inneholder spesielt sensitive personopplysninger [Lov om behandling av personopplysninger(personopplysningsloven)-KAPITTEL || Prinsipper - Lovdata](https://lovdata.no/dokument/NL/lov/2018-06-15-38/KAPITTEL_gdpr-2#gdpr/a9)
+  - opplysninger om etnisk opprinnelse
+  - opplysninger om politisk oppfatning
+  - opplysninger om religion
+  - opplysninger om filosofisk overbevisning
+  - opplysninger om fagforeningsmedlemskap
+  - genetiske opplysninger
+  - biometriske opplysninger med det formål å entydig identifisere noen
+  - helseopplysninger
+  - opplysninger om seksuelle forhold
+  - opplysninger om seksuell legning
+measurement_type: |
+  Måletype som en kvantitativ variabelen tilhører, f.eks.  valuta, areal osv. Disse ligger i kodeverket [SSB måletyper/måleenheter](https://www.ssb.no/klass/klassifikasjoner/303/koder)
+valid_from: |
+  Datoen variabeldefinisjonen er gyldig  f.o.m.
+valid_until: |
+  Datoen variabeldefinisjonens var gyldig t.o.m. Settes hvis definisjonen skal erstattet av en ny definisjon (med en ny gyldighetsperiode), eller variabelen ikke lenger skal brukes.
+external_reference_uri:  |
+  En peker (URI) til ekstern definisjon/dokumentasjon, f.eks. ei webside som er relevant for variabelen.
+comment: |
+  Her kan en sette inn eventuelle tilleggsopplysninger som ikke hører hjemme i selve definisjonen. Variabelen “Landbakgrunn” har f.eks. merknaden “Fra og med 1.1.2003 ble definisjon endret til også å trekke inn besteforeldrenes fødeland”.
+related_variable_definition_uris: |
+  Her kan en legge inn URI(er) til andre variabler som er relevante. Eksempelvis er variabelen “Inntekt etter skatt” en beregnet variabel der  “Yrkesinntekter” og “Kapitalinntekter” inngår i beregningen. En kan da legge inn deres URI-er i dette feltet.
+contact: |
+  Her dokumenterer en navn og epost for person eller gruppe som kan svare på spørsmål.
+variable_status: |
+  Livssyklus for variabelen. Denne har tre kategorier: Utkast, Publisert internt og Publisert eksternt.
+id: |
+  Unik SSB identifikator for variabeldefinisjonen. Denne blir maskingenerert.
+  Variabeldefinisjoner med ulike gyldighetsperioder har samme ID (og samme kortnavn).
+patch_id: |
+  Løpenummer som identifiserer en patch, endring, for en variabeldefinisjon.
+owner: |
+  Eier av variabelen dvs. ansvarlig Dapla-team (statistikk-team) og informasjon om tilgangsstyringsgrupper. Team-tilhørighet settes automatisk til det samme som teamtilhørigheten til den som oppretter variabelen.
+  Eksempel:
+  team: ledstil
+  groups: [developers]
+created_at: |
+  Datoen variabelen ble opprettet. Denne er maskingenerert.
+created_by: |
+  Personen som har opprettet variabelen (initialer). Dette er maskingenerert.
+last_updated_at: |
+  Dato da variabelen sist ble oppdatert. Denne er maskingenerert.
+last_updated_by: |
+  Personen (initialer) som sist utførte en endring i variabelen. Denne er maskingenerert.

dapla_metadata/variable_definitions/vardef.py

@@ -1,22 +1,38 @@
+import logging
 from datetime import date
+from os import PathLike
+from pathlib import Path
 
-from dapla_metadata.variable_definitions import config
-from dapla_metadata.variable_definitions._client import VardefClient
-from dapla_metadata.variable_definitions.exceptions import vardef_exception_handler
-from dapla_metadata.variable_definitions.generated.vardef_client.api.data_migration_api import (
+from dapla_metadata.variable_definitions._generated.vardef_client.api.data_migration_api import (
     DataMigrationApi,
 )
-from dapla_metadata.variable_definitions.generated.vardef_client.api.draft_variable_definitions_api import (
+from dapla_metadata.variable_definitions._generated.vardef_client.api.draft_variable_definitions_api import (
     DraftVariableDefinitionsApi,
 )
-from dapla_metadata.variable_definitions.generated.vardef_client.api.variable_definitions_api import (
+from dapla_metadata.variable_definitions._generated.vardef_client.api.variable_definitions_api import (
     VariableDefinitionsApi,
 )
-from dapla_metadata.variable_definitions.generated.vardef_client.models.draft import (
+from dapla_metadata.variable_definitions._generated.vardef_client.models.draft import (
     Draft,
 )
+from dapla_metadata.variable_definitions._utils import config
+from dapla_metadata.variable_definitions._utils._client import VardefClient
+from dapla_metadata.variable_definitions._utils.template_files import (
+    _find_latest_template_file,
+)
+from dapla_metadata.variable_definitions._utils.template_files import (
+    create_template_yaml,
+)
+from dapla_metadata.variable_definitions._utils.variable_definition_files import (
+    _read_file_to_model,
+)
+from dapla_metadata.variable_definitions.exceptions import VariableNotFoundError
+from dapla_metadata.variable_definitions.exceptions import vardef_exception_handler
+from dapla_metadata.variable_definitions.exceptions import vardef_file_error_handler
 from dapla_metadata.variable_definitions.variable_definition import VariableDefinition
 
+logger = logging.getLogger(__name__)
+
 
 class Vardef:
     """Create, maintain and read Variable Definitions.
@@ -82,7 +98,7 @@ class Vardef:
     @vardef_exception_handler
     def create_draft(cls, draft: Draft) -> VariableDefinition:
         """Create a Draft Variable Definition."""
-        return VariableDefinition.from_model(
+        new_variable = VariableDefinition.from_model(
             DraftVariableDefinitionsApi(
                 VardefClient.get_client(),
             ).create_variable_definition(
@@ -91,6 +107,39 @@ class Vardef:
             ),
         )
 
+        logger.info(
+            "Successfully created variable definition '%s' with ID '%s'",
+            new_variable.short_name,
+            new_variable.id,
+        )
+        return new_variable
+
+    @classmethod
+    @vardef_file_error_handler
+    def create_draft_from_file(
+        cls,
+        file_path: PathLike[str] | None = None,
+    ) -> VariableDefinition:
+        """Create a Draft Variable Definition from a stored yaml file.
+
+        By default the latest template file in the default directory is chosen, this may be overridden by providing a value for the optional `file_path` parameter.
+
+        Args:
+            file_path (PathLike[str], optional): Supply a file path to override the automatic one. Defaults to None.
+
+        Raises:
+            FileNotFoundError: When a file can't be found.
+
+        Returns:
+            VariableDefinition: The created draft variable definition.
+        """
+        return cls.create_draft(
+            _read_file_to_model(
+                file_path or _find_latest_template_file(),
+                Draft,
+            ),
+        )
+
     @classmethod
     @vardef_exception_handler
     def migrate_from_vardok(cls, vardok_id: str) -> VariableDefinition:
@@ -106,7 +155,7 @@ class Vardef:
         Returns:
             VariableDefinition: The migrated Variable Definition in Vardef.
         """
-        return VariableDefinition.from_model(
+        migrated_variable = VariableDefinition.from_model(
             DataMigrationApi(
                 VardefClient.get_client(),
             ).create_variable_definition_from_var_dok(
@@ -115,6 +164,13 @@ class Vardef:
             ),
         )
 
+        logger.info(
+            "Successfully migrated variable definition '%s' with ID '%s'",
+            migrated_variable.short_name,
+            migrated_variable.id,
+        )
+        return migrated_variable
+
     @classmethod
     @vardef_exception_handler
     def list_variable_definitions(
@@ -146,7 +202,7 @@ class Vardef:
 
     @classmethod
     @vardef_exception_handler
-    def get_variable_definition(
+    def get_variable_definition_by_id(
         cls,
         variable_definition_id: str,
         date_of_validity: date | None = None,
@@ -171,3 +227,68 @@ class Vardef:
                 date_of_validity=date_of_validity,
             ),
         )
+
+    @classmethod
+    @vardef_exception_handler
+    def get_variable_definition_by_shortname(
+        cls,
+        short_name: str,
+        date_of_validity: date | None = None,
+    ) -> VariableDefinition:
+        """Retrieve a Variable Definition by ID or short name.
+
+        Args:
+            short_name (str): The short name of the Variable Definition.
+            date_of_validity (date | None, optional): Filter by validity date. Defaults to None.
+
+        Returns:
+            VariableDefinition: The retrieved Variable Definition.
+
+        Raises:
+            VariableNotFoundError: If no matching Variable Definition is found.
+            ValueError: If multiple variables with the same shortname is found.
+        """
+        client = VardefClient.get_client()
+        api = VariableDefinitionsApi(client)
+
+        variable_definitions = api.list_variable_definitions(
+            short_name=short_name,
+            date_of_validity=date_of_validity,
+        )
+
+        if not variable_definitions:
+            msg = f"Variable with short name {short_name} not found"
+            raise VariableNotFoundError(msg)
+        if len(variable_definitions) > 1:
+            msg = f"Lookup by short name {short_name} found multiple variables which should not be possible."
+            raise VariableNotFoundError(msg)
+
+        return VariableDefinition.from_model(variable_definitions[0])
+
+    @classmethod
+    @vardef_file_error_handler
+    def write_template_to_file(cls, custom_file_path: str | None = None) -> Path:
+        """Write template with default values to a yaml file."""
+        file_path = create_template_yaml(
+            custom_directory=Path(custom_file_path) if custom_file_path else None,
+        )
+        logger.info(
+            f"Created editable variable definition template file at {file_path}",  # noqa: G004
+        )
+        return file_path
+
+    @classmethod
+    @vardef_exception_handler
+    def does_short_name_exist(
+        cls,
+        short_name: str,
+    ) -> bool:
+        """Return True if the short name exists in Vardef, otherwise False."""
+        variable_definitions = Vardef.list_variable_definitions()
+        for variable in variable_definitions:
+            if short_name.strip() == variable.short_name:
+                logger.info(
+                    f"Found duplicate short name {short_name}",  # noqa: G004
+                )
+                return True
+        return False

dapla_metadata/variable_definitions/variable_definition.py

@@ -1,47 +1,52 @@
+import logging
 from datetime import date
+from io import StringIO
+from os import PathLike
+from pathlib import Path
 
-from dapla_metadata.variable_definitions import config
-from dapla_metadata.variable_definitions._client import VardefClient
-from dapla_metadata.variable_definitions.exceptions import vardef_exception_handler
-from dapla_metadata.variable_definitions.generated.vardef_client.api.draft_variable_definitions_api import (
+import ruamel.yaml
+from pydantic import ConfigDict
+from pydantic import PrivateAttr
+
+from dapla_metadata.variable_definitions._generated.vardef_client.api.draft_variable_definitions_api import (
     DraftVariableDefinitionsApi,
 )
-from dapla_metadata.variable_definitions.generated.vardef_client.api.patches_api import (
+from dapla_metadata.variable_definitions._generated.vardef_client.api.patches_api import (
     PatchesApi,
 )
-from dapla_metadata.variable_definitions.generated.vardef_client.api.validity_periods_api import (
+from dapla_metadata.variable_definitions._generated.vardef_client.api.validity_periods_api import (
     ValidityPeriodsApi,
 )
-from dapla_metadata.variable_definitions.generated.vardef_client.models.complete_response import (
+from dapla_metadata.variable_definitions._generated.vardef_client.models.complete_response import (
     CompleteResponse,
 )
-from dapla_metadata.variable_definitions.generated.vardef_client.models.patch import (
+from dapla_metadata.variable_definitions._generated.vardef_client.models.patch import (
     Patch,
 )
-from dapla_metadata.variable_definitions.generated.vardef_client.models.update_draft import (
+from dapla_metadata.variable_definitions._generated.vardef_client.models.update_draft import (
     UpdateDraft,
 )
-from dapla_metadata.variable_definitions.generated.vardef_client.models.validity_period import (
+from dapla_metadata.variable_definitions._generated.vardef_client.models.validity_period import (
     ValidityPeriod,
 )
+from dapla_metadata.variable_definitions._generated.vardef_client.models.variable_status import (
+    VariableStatus,
+)
+from dapla_metadata.variable_definitions._utils import config
+from dapla_metadata.variable_definitions._utils._client import VardefClient
+from dapla_metadata.variable_definitions._utils.variable_definition_files import (
+    _read_file_to_model,
+)
+from dapla_metadata.variable_definitions._utils.variable_definition_files import (
+    create_variable_yaml,
+)
+from dapla_metadata.variable_definitions.exceptions import vardef_exception_handler
+from dapla_metadata.variable_definitions.exceptions import vardef_file_error_handler
 
+logger = logging.getLogger(__name__)
 
-class CompletePatchOutput(CompleteResponse):
-    """Complete response For internal users who need all details while maintaining variable definitions."""
-
-    @staticmethod
-    def from_model(
-        model: CompleteResponse,
-    ) -> "CompletePatchOutput":
-        """Create a CompletePatchOutput instance from a CompletePatchOutput."""
-        return CompletePatchOutput.model_construct(**model.model_dump())
-
-    def __str__(self) -> str:
-        """Format as indented JSON."""
-        return self.model_dump_json(indent=2, warnings=False)
 
-
-class VariableDefinition(CompletePatchOutput):
+class VariableDefinition(CompleteResponse):
     """A Variable Definition.
 
     - Provides access to the fields of the specific Variable Definition.
@@ -49,21 +54,33 @@ class VariableDefinition(CompletePatchOutput):
     - Provides methods allowing maintenance of this Variable Definition.
 
     Args:
-        CompletePatchOutput: The Pydantic model superclass, representing a Variable Definition.
+        CompleteResponse: The Pydantic model superclass, representing a Variable Definition.
     """
 
+    _file_path: Path | None = PrivateAttr(None)
+
+    model_config = ConfigDict(use_enum_values=True, str_strip_whitespace=True)
+
+    def get_file_path(self) -> Path | None:
+        """Get the file path where the variable definition has been written to for editing."""
+        return self._file_path
+
+    def set_file_path(self, file_path: Path | None) -> None:
+        """Set the file path where the variable definition has been written to for editing."""
+        self._file_path = file_path
+
     @staticmethod
     def from_model(
         model: CompleteResponse,
     ) -> "VariableDefinition":
-        """Create a VariableDefinition instance from a CompletePatchOutput or CompletePatchOutput."""
+        """Create a VariableDefinition instance from a CompleteResponse."""
         return VariableDefinition.model_construct(**model.model_dump())
 
     @vardef_exception_handler
-    def list_validity_periods(self) -> list[CompletePatchOutput]:
+    def list_validity_periods(self) -> list["VariableDefinition"]:
         """List all Validity Periods for this Variable Definition."""
         return [
-            CompletePatchOutput.from_model(validity_period)
+            VariableDefinition.from_model(validity_period)
             for validity_period in ValidityPeriodsApi(
                 VardefClient.get_client(),
             ).list_validity_periods(
@@ -72,10 +89,10 @@ class VariableDefinition(CompletePatchOutput):
         ]
 
     @vardef_exception_handler
-    def list_patches(self) -> list[CompletePatchOutput]:
+    def list_patches(self) -> list["VariableDefinition"]:
         """List all Patches for this Variable Definition."""
         return [
-            CompletePatchOutput.from_model(patch)
+            VariableDefinition.from_model(patch)
             for patch in PatchesApi(VardefClient.get_client()).list_patches(
                 variable_definition_id=self.id,
             )
@@ -85,7 +102,7 @@ class VariableDefinition(CompletePatchOutput):
     def update_draft(
         self,
         update_draft: UpdateDraft,
-    ) -> CompletePatchOutput:
+    ) -> "VariableDefinition":
         """Update this Variable Definition.
 
         - Variable definition must have status 'DRAFT'.
@@ -95,9 +112,9 @@ class VariableDefinition(CompletePatchOutput):
             update_draft: The input with updated values.
 
         Returns:
-            CompletePatchOutput: Updated Variable definition with all details.
+            VariableDefinition: Updated Variable definition with all details.
         """
-        return CompletePatchOutput.from_model(
+        updated = VariableDefinition.from_model(
             DraftVariableDefinitionsApi(
                 VardefClient.get_client(),
             ).update_variable_definition_by_id(
@@ -106,6 +123,40 @@ class VariableDefinition(CompletePatchOutput):
                 update_draft=update_draft,
             ),
         )
+        self.__dict__.update(updated)
+
+        logger.info(
+            "Successfully updated variable definition '%s' with ID '%s'",
+            updated.short_name,
+            updated.id,
+        )
+        return updated
+
+    @vardef_file_error_handler
+    def update_draft_from_file(
+        self,
+        file_path: PathLike | None = None,
+    ) -> "VariableDefinition":
+        """Update this Variable Definition.
+
+        Will automatically read the relevant file pertaining to this variable definition. Can
+        be overridden by specifying the file_path parameter.
+
+        - Variable definition must have status 'DRAFT'.
+        - Supply only the fields to be changed. Other fields will retain their current values.
+
+        Args:
+            file_path: Optionally specify the path to read from.
+
+        Returns:
+            VariableDefinition: Updated Variable definition with all details.
+        """
+        return self.update_draft(
+            _read_file_to_model(
+                file_path or self.get_file_path(),
+                UpdateDraft,
+            ),
+        )
 
     @vardef_exception_handler
     def delete_draft(
@@ -128,16 +179,16 @@ class VariableDefinition(CompletePatchOutput):
         return f"Variable {self.id} safely deleted"
 
     @vardef_exception_handler
-    def get_patch(self, patch_id: int) -> CompletePatchOutput:
+    def get_patch(self, patch_id: int) -> "VariableDefinition":
         """Get a single Patch by ID.
 
         Args:
             patch_id (int): The ID of the patch.
 
         Returns:
-            CompletePatchOutput: The desired patch.
+            VariableDefinition: The desired patch.
         """
-        return CompletePatchOutput.from_model(
+        return VariableDefinition.from_model(
             PatchesApi(VardefClient.get_client()).get_patch(
                 variable_definition_id=self.id,
                 patch_id=patch_id,
@@ -149,7 +200,7 @@ class VariableDefinition(CompletePatchOutput):
         self,
         patch: Patch,
         valid_from: date | None = None,
-    ) -> CompletePatchOutput:
+    ) -> "VariableDefinition":
         """Create a new Patch for this Variable Definition.
 
         Patches are to be used for minor changes which don't require a new Validity Period.
@@ -167,10 +218,10 @@ class VariableDefinition(CompletePatchOutput):
                         created in the last validity period.
 
         Returns:
-            CompletePatchOutput: Variable Definition with all details.
+            VariableDefinition: Variable Definition with all details.
 
         """
-        return CompletePatchOutput.from_model(
+        new_patch = VariableDefinition.from_model(
             PatchesApi(
                 VardefClient.get_client(),
             ).create_patch(
@@ -180,12 +231,57 @@ class VariableDefinition(CompletePatchOutput):
                 valid_from=valid_from,
             ),
         )
+        self.__dict__.update(new_patch)
+
+        logger.info(
+            "Successfully created patch with patch ID '%s' for variable definition '%s' with ID '%s'",
+            new_patch.patch_id,
+            new_patch.short_name,
+            new_patch.id,
+        )
+        return new_patch
+
+    @vardef_file_error_handler
+    def create_patch_from_file(
+        self,
+        file_path: PathLike | None = None,
+        valid_from: date | None = None,
+    ) -> "VariableDefinition":
+        """Create a new Patch for this Variable Definition from a file.
+
+        Will automatically read the relevant file pertaining to this variable definition. Can
+        be overridden by specifying the file_path parameter.
+
+        Patches are to be used for minor changes which don't require a new Validity Period.
+        Examples of reasons for creating a new Patch:
+          - Correcting a typo
+          - Adding a translation
+          - Adding a subject field
+
+        Supply only the fields to be changed. Other fields will retain their current values.
+
+        Args:
+            file_path: Optionally specify the path to read from.
+            valid_from: Optional date for selecting a Validity Period to create patch in. The date must
+                        exactly match the Validity Period `valid_from`. If value is None the patch is
+                        created in the last validity period.
+
+        Returns:
+            VariableDefinition: Variable Definition with all details.
+        """
+        return self.create_patch(
+            patch=_read_file_to_model(
+                file_path or self.get_file_path(),
+                Patch,
+            ),
+            valid_from=valid_from,
+        )
 
     @vardef_exception_handler
     def create_validity_period(
         self,
         validity_period: ValidityPeriod,
-    ) -> CompletePatchOutput:
+    ) -> "VariableDefinition":
         """Create a new Validity Period for this Variable Definition.
 
         In order to create a new Validity Period input must contain updated
@@ -199,9 +295,9 @@ class VariableDefinition(CompletePatchOutput):
             validity_period: The input for new Validity Period
 
         Returns:
-            CompletePatchOutput: Variable Definition with all details.
+            VariableDefinition: Variable Definition with all details.
         """
-        return CompletePatchOutput.from_model(
+        new_validity_period = VariableDefinition.from_model(
             ValidityPeriodsApi(
                 VardefClient.get_client(),
             ).create_validity_period(
@@ -210,3 +306,115 @@ class VariableDefinition(CompletePatchOutput):
                 validity_period=validity_period,
             ),
         )
+        self.__dict__.update(new_validity_period)
+
+        logger.info(
+            "Successfully created validity period that is valid from '%s' for variable definition '%s' with ID '%s'",
+            new_validity_period.valid_from,
+            new_validity_period.short_name,
+            new_validity_period.id,
+        )
+        return new_validity_period
+
+    @vardef_file_error_handler
+    def create_validity_period_from_file(
+        self,
+        file_path: PathLike | None = None,
+    ) -> "VariableDefinition":
+        """Create a new ValidityPeriod for this Variable Definition from a file.
+
+        In order to create a new Validity Period the input file must contain updated
+        'definition' text for all present languages and a new valid from.
+
+        Args:
+            file_path: Optionally specify the path to read from.
+
+        Returns:
+            VariableDefinition: Variable Definition with all details.
+        """
+        return self.create_validity_period(
+            validity_period=_read_file_to_model(
+                file_path or self.get_file_path(),
+                ValidityPeriod,
+            ),
+        )
+
+    def publish_internal(self) -> "VariableDefinition":
+        """Publish this variable definition internally."""
+        if self.variable_status != VariableStatus.DRAFT.name:
+            msg = "That won't work here. Only variable definitions with status DRAFT may be published internally."
+            raise ValueError(
+                msg,
+            )
+        update = self.update_draft(
+            UpdateDraft(variable_status=VariableStatus.PUBLISHED_INTERNAL),
+        )
+        logger.info(
+            "Variable definition '%s' with ID '%s' successfully published, new status: %s",
+            update.short_name,
+            update.id,
+            update.variable_status,
+        )
+        return update
+
+    def publish_external(self) -> "VariableDefinition":
+        """Publish this variable definition externally."""
+        if self.variable_status == VariableStatus.PUBLISHED_EXTERNAL.name:
+            msg = "That won't work here. The variable definition is already published."
+            raise ValueError(
+                msg,
+            )
+        if self.variable_status is VariableStatus.DRAFT:
+            update = self.update_draft(
+                UpdateDraft(variable_status=VariableStatus.PUBLISHED_EXTERNAL),
+            )
+        else:
+            update = self.create_patch(
+                Patch(variable_status=VariableStatus.PUBLISHED_EXTERNAL),
+            )
+        logger.info(
+            "Variable definition '%s' with ID '%s' successfully published, new status: %s",
+            update.short_name,
+            update.id,
+            update.variable_status,
+        )
+        return update
+
+    def to_file(self) -> "VariableDefinition":
+        """Write this variable definition to file."""
+        file_path = create_variable_yaml(
+            model_instance=self,
+        )
+        self.set_file_path(file_path)
+        logger.info(
+            f"Created editable variable definition file at {file_path}",  # noqa: G004
+        )
+        return self
+
+    def to_dict(self) -> dict:
+        """Return as dictionary."""
+        return super().to_dict()
+
+    def __str__(self) -> str:
+        """Format as indented YAML."""
+        return self._convert_to_yaml_output()
+
+    def __repr__(self) -> str:
+        """Format as indented YAML."""
+        return self._convert_to_yaml_output()
+
+    def _convert_to_yaml_output(self) -> str:
+        stream = StringIO()
+        with ruamel.yaml.YAML(
+            output=stream,
+        ) as yaml:
+            yaml.default_flow_style = False
+            yaml.allow_unicode = True
+            yaml.dump(
+                self.model_dump(
+                    mode="json",
+                    serialize_as_any=True,
+                    warnings="error",
+                ),
+            )
+        return stream.getvalue()