dapla-toolbelt-metadata 0.3.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

dapla_metadata/variable_definitions/generated/vardef_client/rest.py

@@ -0,0 +1,249 @@
+"""Variable Definitions
+
+## Introduction  Variable Definitions are centralized definitions of concrete variables which are typically present in multiple datasets. Variable Definitions support standardization of data and metadata and facilitate sharing and joining of data by clarifying when variables have an identical definition.  ## Maintenance of Variable Definitions This API allows for creation, maintenance and access of Variable Definitions.  ### Ownership Creation and maintenance of variables may only be performed by Statistics Norway employees representing a specific Dapla team, who are defined as the owners of a given Variable Definition. The team an owner represents must be specified when making a request through the `active_group` query parameter. All maintenance is to be performed by the owners, with no intervention from administrators.  ### Status All Variable Definitions have an associated status. The possible values for status are `DRAFT`, `PUBLISHED_INTERNAL` and `PUBLISHED_EXTERNAL`.   #### Draft When a Variable Definition is created it is assigned the status `DRAFT`. Under this status the Variable Definition is:  - Only visible to Statistics Norway employees. - Mutable (it may be changed directly without need for versioning). - Not suitable to refer to from other systems.  This status may be changed to `PUBLISHED_INTERNAL` or `PUBLISHED_EXTERNAL` with a direct update.  #### Published Internal Under this status the Variable Definition is:  - Only visible to Statistics Norway employees. - Immutable (all changes are versioned). - Suitable to refer to in internal systems for statistics production. - Not suitable to refer to for external use (for example in Statistikkbanken).  This status may be changed to `PUBLISHED_EXTERNAL` by creating a Patch version.  #### Published External Under this status the Variable Definition is:  - Visible to the general public. - Immutable (all changes are versioned). - Suitable to refer to from any system.  This status may not be changed as it would break immutability. If a Variable Definition is no longer relevant then its period of validity should be ended by specifying a `valid_until` date in a Patch version.  ### Immutability Variable Definitions are immutable. This means that any changes must be performed in a strict versioning system. Consumers can avoid being exposed to breaking changes by specifying a `date_of_validity` when they request a Variable Definition.  #### Patches Patches are for changes which do not affect the fundamental meaning of the Variable Definition.  #### Validity Periods Validity Periods are versions with a period defined by a `valid_from` date and optionally a `valid_until` date. If the fundamental meaning of a Variable Definition is to be changed, it should be done by creating a new Validity Period.
+
+The version of the OpenAPI document: 0.1
+Contact: metadata@ssb.no
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""
+
+import io
+import json
+import re
+import ssl
+
+import urllib3
+
+from .exceptions import ApiException
+from .exceptions import ApiValueError
+
+SUPPORTED_SOCKS_PROXIES = {"socks5", "socks5h", "socks4", "socks4a"}
+RESTResponseType = urllib3.HTTPResponse
+
+
+def is_socks_proxy_url(url):
+    if url is None:
+        return False
+    split_section = url.split("://")
+    if len(split_section) < 2:
+        return False
+    return split_section[0].lower() in SUPPORTED_SOCKS_PROXIES
+
+
+class RESTResponse(io.IOBase):
+    def __init__(self, resp) -> None:
+        self.response = resp
+        self.status = resp.status
+        self.reason = resp.reason
+        self.data = None
+
+    def read(self):
+        if self.data is None:
+            self.data = self.response.data
+        return self.data
+
+    def getheaders(self):
+        """Returns a dictionary of the response headers."""
+        return self.response.headers
+
+    def getheader(self, name, default=None):
+        """Returns a given response header."""
+        return self.response.headers.get(name, default)
+
+
+class RESTClientObject:
+    def __init__(self, configuration) -> None:
+        # urllib3.PoolManager will pass all kw parameters to connectionpool
+        # https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/poolmanager.py#L75
+        # https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/connectionpool.py#L680
+        # Custom SSL certificates and client certificates: http://urllib3.readthedocs.io/en/latest/advanced-usage.html
+
+        # cert_reqs
+        if configuration.verify_ssl:
+            cert_reqs = ssl.CERT_REQUIRED
+        else:
+            cert_reqs = ssl.CERT_NONE
+
+        pool_args = {
+            "cert_reqs": cert_reqs,
+            "ca_certs": configuration.ssl_ca_cert,
+            "cert_file": configuration.cert_file,
+            "key_file": configuration.key_file,
+        }
+        if configuration.assert_hostname is not None:
+            pool_args["assert_hostname"] = configuration.assert_hostname
+
+        if configuration.retries is not None:
+            pool_args["retries"] = configuration.retries
+
+        if configuration.tls_server_name:
+            pool_args["server_hostname"] = configuration.tls_server_name
+
+        if configuration.socket_options is not None:
+            pool_args["socket_options"] = configuration.socket_options
+
+        if configuration.connection_pool_maxsize is not None:
+            pool_args["maxsize"] = configuration.connection_pool_maxsize
+
+        # https pool manager
+        self.pool_manager: urllib3.PoolManager
+
+        if configuration.proxy:
+            if is_socks_proxy_url(configuration.proxy):
+                from urllib3.contrib.socks import SOCKSProxyManager
+
+                pool_args["proxy_url"] = configuration.proxy
+                pool_args["headers"] = configuration.proxy_headers
+                self.pool_manager = SOCKSProxyManager(**pool_args)
+            else:
+                pool_args["proxy_url"] = configuration.proxy
+                pool_args["proxy_headers"] = configuration.proxy_headers
+                self.pool_manager = urllib3.ProxyManager(**pool_args)
+        else:
+            self.pool_manager = urllib3.PoolManager(**pool_args)
+
+    def request(
+        self,
+        method,
+        url,
+        headers=None,
+        body=None,
+        post_params=None,
+        _request_timeout=None,
+    ):
+        """Perform requests.
+
+        :param method: http request method
+        :param url: http request url
+        :param headers: http request headers
+        :param body: request json body, for `application/json`
+        :param post_params: request post parameters,
+                            `application/x-www-form-urlencoded`
+                            and `multipart/form-data`
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        """
+        method = method.upper()
+        assert method in [
+            "GET",
+            "HEAD",
+            "DELETE",
+            "POST",
+            "PUT",
+            "PATCH",
+            "OPTIONS",
+        ]
+
+        if post_params and body:
+            raise ApiValueError(
+                "body parameter cannot be used with post_params parameter.",
+            )
+
+        post_params = post_params or {}
+        headers = headers or {}
+
+        timeout = None
+        if _request_timeout:
+            if isinstance(_request_timeout, (int, float)):
+                timeout = urllib3.Timeout(total=_request_timeout)
+            elif isinstance(_request_timeout, tuple) and len(_request_timeout) == 2:
+                timeout = urllib3.Timeout(
+                    connect=_request_timeout[0],
+                    read=_request_timeout[1],
+                )
+
+        try:
+            # For `POST`, `PUT`, `PATCH`, `OPTIONS`, `DELETE`
+            if method in ["POST", "PUT", "PATCH", "OPTIONS", "DELETE"]:
+                # no content type provided or payload is json
+                content_type = headers.get("Content-Type")
+                if not content_type or re.search("json", content_type, re.IGNORECASE):
+                    request_body = None
+                    if body is not None:
+                        request_body = json.dumps(body)
+                    r = self.pool_manager.request(
+                        method,
+                        url,
+                        body=request_body,
+                        timeout=timeout,
+                        headers=headers,
+                        preload_content=False,
+                    )
+                elif content_type == "application/x-www-form-urlencoded":
+                    r = self.pool_manager.request(
+                        method,
+                        url,
+                        fields=post_params,
+                        encode_multipart=False,
+                        timeout=timeout,
+                        headers=headers,
+                        preload_content=False,
+                    )
+                elif content_type == "multipart/form-data":
+                    # must del headers['Content-Type'], or the correct
+                    # Content-Type which generated by urllib3 will be
+                    # overwritten.
+                    del headers["Content-Type"]
+                    # Ensures that dict objects are serialized
+                    post_params = [
+                        (a, json.dumps(b)) if isinstance(b, dict) else (a, b)
+                        for a, b in post_params
+                    ]
+                    r = self.pool_manager.request(
+                        method,
+                        url,
+                        fields=post_params,
+                        encode_multipart=True,
+                        timeout=timeout,
+                        headers=headers,
+                        preload_content=False,
+                    )
+                # Pass a `string` parameter directly in the body to support
+                # other content types than JSON when `body` argument is
+                # provided in serialized form.
+                elif isinstance(body, str) or isinstance(body, bytes):
+                    r = self.pool_manager.request(
+                        method,
+                        url,
+                        body=body,
+                        timeout=timeout,
+                        headers=headers,
+                        preload_content=False,
+                    )
+                elif headers["Content-Type"].startswith("text/") and isinstance(
+                    body, bool
+                ):
+                    request_body = "true" if body else "false"
+                    r = self.pool_manager.request(
+                        method,
+                        url,
+                        body=request_body,
+                        preload_content=False,
+                        timeout=timeout,
+                        headers=headers,
+                    )
+                else:
+                    # Cannot generate the request from given parameters
+                    msg = """Cannot prepare a request message for provided
+                             arguments. Please check that your arguments match
+                             declared content type."""
+                    raise ApiException(status=0, reason=msg)
+            # For `GET`, `HEAD`
+            else:
+                r = self.pool_manager.request(
+                    method,
+                    url,
+                    fields={},
+                    timeout=timeout,
+                    headers=headers,
+                    preload_content=False,
+                )
+        except urllib3.exceptions.SSLError as e:
+            msg = "\n".join([type(e).__name__, str(e)])
+            raise ApiException(status=0, reason=msg)
+
+        return RESTResponse(r)

dapla_metadata/variable_definitions/vardef.py

@@ -0,0 +1,173 @@
+from datetime import date
+
+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 (
+    DataMigrationApi,
+)
+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 (
+    VariableDefinitionsApi,
+)
+from dapla_metadata.variable_definitions.generated.vardef_client.models.draft import (
+    Draft,
+)
+from dapla_metadata.variable_definitions.variable_definition import VariableDefinition
+
+
+class Vardef:
+    """Create, maintain and read Variable Definitions.
+
+    ====================
+    Variable Definitions
+    ====================
+
+    Variable Definitions are centralized definitions of concrete variables which are typically present in multiple datasets. Variable Definitions
+    support standardization of data and metadata and facilitate sharing and joining of data by clarifying when variables have an identical
+    definition.
+
+    The methods in this class allow for creation, maintenance and access of Variable Definitions.
+
+    Creation and maintenance of variables may only be performed by Statistics Norway employees representing a specific Dapla team, who are defined
+    as the owners of a given Variable Definition. The group a user represents is chosen when starting a service in Dapla Lab. This class will
+    seamlessly detect this and send it to the API. All maintenance is to be performed by the owners, with no intervention from administrators.
+
+    ======
+    Status
+    ======
+    All Variable Definitions have an associated status. The possible values for status are `DRAFT`, `PUBLISHED_INTERNAL` and `PUBLISHED_EXTERNAL`.
+
+    -----
+    Draft
+    -----
+    When a Variable Definition is created it is assigned the status `DRAFT`. Under this status the Variable Definition is:
+    * Only visible to Statistics Norway employees.
+    * Mutable (it may be changed directly without need for versioning).
+    * Not suitable to refer to from other systems.
+    This status may be changed to `PUBLISHED_INTERNAL` or `PUBLISHED_EXTERNAL` with a direct update.
+
+    ------------------
+    Published Internal
+    ------------------
+    Under this status the Variable Definition is:
+    * Only visible to Statistics Norway employees.
+    * Immutable (all changes are versioned).
+    * Suitable to refer to in internal systems for statistics production.
+    * Not suitable to refer to for external use (for example in Statistikkbanken).
+
+    This status may be changed to `PUBLISHED_EXTERNAL` by creating a Patch version.
+
+    ------------------
+    Published External
+    ------------------
+    Under this status the Variable Definition is:
+    * Visible to the general public.
+    * Immutable (all changes are versioned).
+    * Suitable to refer to from any system.
+
+    This status may not be changed as it would break immutability. If a Variable Definition is no longer relevant then its period of validity
+    should be ended by specifying a `valid_until` date in a Patch version.
+
+    ============
+    Immutability
+    ============
+    Variable Definitions are immutable. This means that any changes must be performed in a strict versioning system. Consumers can avoid
+    being exposed to breaking changes by specifying a `date_of_validity` when they request a Variable Definition.
+    """
+
+    @classmethod
+    @vardef_exception_handler
+    def create_draft(cls, draft: Draft) -> VariableDefinition:
+        """Create a Draft Variable Definition."""
+        return VariableDefinition.from_model(
+            DraftVariableDefinitionsApi(
+                VardefClient.get_client(),
+            ).create_variable_definition(
+                active_group=config.get_active_group(),
+                draft=draft,
+            ),
+        )
+
+    @classmethod
+    @vardef_exception_handler
+    def migrate_from_vardok(cls, vardok_id: str) -> VariableDefinition:
+        """Migrate a Variable Definition from Vardok to Vardef.
+
+        - Each Vardok Variable Definition may only be migrated once.
+        - The Dapla team of the person who performs the migration will be set as the owner.
+        - All metadata should be checked for correctness before publication.
+
+        Args:
+            vardok_id (str): The ID of a Variable Definition in Vardok.
+
+        Returns:
+            VariableDefinition: The migrated Variable Definition in Vardef.
+        """
+        return VariableDefinition.from_model(
+            DataMigrationApi(
+                VardefClient.get_client(),
+            ).create_variable_definition_from_var_dok(
+                active_group=config.get_active_group(),
+                vardok_id=vardok_id,
+            ),
+        )
+
+    @classmethod
+    @vardef_exception_handler
+    def list_variable_definitions(
+        cls,
+        date_of_validity: date | None = None,
+    ) -> list[VariableDefinition]:
+        """List variable definitions.
+
+        ---------
+        Filtering
+        ---------
+        If no filter arguments are provided then all Variable Definitions are returned. See the documentation for the
+        individual arguments to understand their effect. Filter arguments are combined with AND logic.
+
+        Args:
+            date_of_validity (date | None, optional): List only variable definitions which are valid on this date. Defaults to None.
+
+        Returns:
+            list[VariableDefinition]: The list of Variable Definitions.
+        """
+        return [
+            VariableDefinition.from_model(definition)
+            for definition in VariableDefinitionsApi(
+                VardefClient.get_client(),
+            ).list_variable_definitions(
+                date_of_validity=date_of_validity,
+            )
+        ]
+
+    @classmethod
+    @vardef_exception_handler
+    def get_variable_definition(
+        cls,
+        variable_definition_id: str,
+        date_of_validity: date | None = None,
+    ) -> VariableDefinition:
+        """Get a Variable Definition by ID.
+
+        Args:
+            variable_definition_id (str): The ID of the desired Variable Definition
+            date_of_validity (date | None, optional): List only variable definitions which are valid on this date. Defaults to None.
+
+        Returns:
+            VariableDefinition: The Variable Definition.
+
+        Raises:
+            NotFoundException when the given ID is not found
+        """
+        return VariableDefinition.from_model(
+            VariableDefinitionsApi(
+                VardefClient.get_client(),
+            ).get_variable_definition_by_id(
+                variable_definition_id=variable_definition_id,
+                date_of_validity=date_of_validity,
+            ),
+        )

dapla_metadata/variable_definitions/variable_definition.py

@@ -0,0 +1,212 @@
+from datetime import date
+
+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 (
+    DraftVariableDefinitionsApi,
+)
+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 (
+    ValidityPeriodsApi,
+)
+from dapla_metadata.variable_definitions.generated.vardef_client.models.complete_response import (
+    CompleteResponse,
+)
+from dapla_metadata.variable_definitions.generated.vardef_client.models.patch import (
+    Patch,
+)
+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 (
+    ValidityPeriod,
+)
+
+
+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):
+    """A Variable Definition.
+
+    - Provides access to the fields of the specific Variable Definition.
+    - Provides methods to access Patches and Validity Periods of this Variable Definition.
+    - Provides methods allowing maintenance of this Variable Definition.
+
+    Args:
+        CompletePatchOutput: The Pydantic model superclass, representing a Variable Definition.
+    """
+
+    @staticmethod
+    def from_model(
+        model: CompleteResponse,
+    ) -> "VariableDefinition":
+        """Create a VariableDefinition instance from a CompletePatchOutput or CompletePatchOutput."""
+        return VariableDefinition.model_construct(**model.model_dump())
+
+    @vardef_exception_handler
+    def list_validity_periods(self) -> list[CompletePatchOutput]:
+        """List all Validity Periods for this Variable Definition."""
+        return [
+            CompletePatchOutput.from_model(validity_period)
+            for validity_period in ValidityPeriodsApi(
+                VardefClient.get_client(),
+            ).list_validity_periods(
+                variable_definition_id=self.id,
+            )
+        ]
+
+    @vardef_exception_handler
+    def list_patches(self) -> list[CompletePatchOutput]:
+        """List all Patches for this Variable Definition."""
+        return [
+            CompletePatchOutput.from_model(patch)
+            for patch in PatchesApi(VardefClient.get_client()).list_patches(
+                variable_definition_id=self.id,
+            )
+        ]
+
+    @vardef_exception_handler
+    def update_draft(
+        self,
+        update_draft: UpdateDraft,
+    ) -> CompletePatchOutput:
+        """Update this Variable Definition.
+
+        - Variable definition must have status 'DRAFT'.
+        - Supply only the fields to be changed. Other fields will retain their current values.
+
+        Args:
+            update_draft: The input with updated values.
+
+        Returns:
+            CompletePatchOutput: Updated Variable definition with all details.
+        """
+        return CompletePatchOutput.from_model(
+            DraftVariableDefinitionsApi(
+                VardefClient.get_client(),
+            ).update_variable_definition_by_id(
+                variable_definition_id=self.id,
+                active_group=config.get_active_group(),
+                update_draft=update_draft,
+            ),
+        )
+
+    @vardef_exception_handler
+    def delete_draft(
+        self,
+    ) -> str:
+        """Delete this Variable definition.
+
+        Variable definition must have status 'DRAFT'.
+
+        Returns:
+            str: A message if the operation was succsessful.
+
+        """
+        DraftVariableDefinitionsApi(
+            VardefClient.get_client(),
+        ).delete_variable_definition_by_id(
+            variable_definition_id=self.id,
+            active_group=config.get_active_group(),
+        )
+        return f"Variable {self.id} safely deleted"
+
+    @vardef_exception_handler
+    def get_patch(self, patch_id: int) -> CompletePatchOutput:
+        """Get a single Patch by ID.
+
+        Args:
+            patch_id (int): The ID of the patch.
+
+        Returns:
+            CompletePatchOutput: The desired patch.
+        """
+        return CompletePatchOutput.from_model(
+            PatchesApi(VardefClient.get_client()).get_patch(
+                variable_definition_id=self.id,
+                patch_id=patch_id,
+            ),
+        )
+
+    @vardef_exception_handler
+    def create_patch(
+        self,
+        patch: Patch,
+        valid_from: date | None = None,
+    ) -> CompletePatchOutput:
+        """Create a new Patch for this Variable Definition.
+
+        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:
+            patch: The input for a new patch.
+            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:
+            CompletePatchOutput: Variable Definition with all details.
+
+        """
+        return CompletePatchOutput.from_model(
+            PatchesApi(
+                VardefClient.get_client(),
+            ).create_patch(
+                variable_definition_id=self.id,
+                active_group=config.get_active_group(),
+                patch=patch,
+                valid_from=valid_from,
+            ),
+        )
+
+    @vardef_exception_handler
+    def create_validity_period(
+        self,
+        validity_period: ValidityPeriod,
+    ) -> CompletePatchOutput:
+        """Create a new Validity Period for this Variable Definition.
+
+        In order to create a new Validity Period input must contain updated
+        'definition' text for all present languages and a new valid from.
+
+        A new Validity Period should be created only when the fundamental definition
+        of the variable has changed. This way the previous definition can be preserved
+        for use in historical data.
+
+        Args:
+            validity_period: The input for new Validity Period
+
+        Returns:
+            CompletePatchOutput: Variable Definition with all details.
+        """
+        return CompletePatchOutput.from_model(
+            ValidityPeriodsApi(
+                VardefClient.get_client(),
+            ).create_validity_period(
+                variable_definition_id=self.id,
+                active_group=config.get_active_group(),
+                validity_period=validity_period,
+            ),
+        )

{dapla_toolbelt_metadata-0.3.0.dist-info → dapla_toolbelt_metadata-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dapla-toolbelt-metadata
-Version: 0.3.0
+Version: 0.4.1
 Summary: Dapla Toolbelt Metadata
 Home-page: https://github.com/statisticsnorway/dapla-toolbelt-metadata
 License: MIT