ssb-klass-python 1.0.1__tar.gz → 1.0.2__tar.gz

{ssb_klass_python-1.0.1 → ssb_klass_python-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ssb-klass-python
-Version: 1.0.1
+Version: 1.0.2
 Summary: A Python package built on top of KLASS's API for retrieving classifications, codes, correspondences etc.
 License: MIT
 Author: Carl Corneil, ssb-pythonistas

{ssb_klass_python-1.0.1 → ssb_klass_python-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "ssb-klass-python"
-version = "1.0.1"
+version = "1.0.2"
 description = "A Python package built on top of KLASS's API for retrieving classifications, codes, correspondences etc."
 authors = ["Carl Corneil, ssb-pythonistas <ssb-pythonistas@ssb.no>"]
 license = "MIT"

{ssb_klass_python-1.0.1 → ssb_klass_python-1.0.2}/src/klass/classes/classification.py

@@ -1,14 +1,19 @@
+from typing import Literal
+
 import pandas as pd
+from typing_extensions import Self
 
-from klass.classes.codes import KlassCodes
-from klass.classes.correspondence import KlassCorrespondence
-from klass.classes.variant import KlassVariant
-from klass.classes.variant import KlassVariantSearchByName
-from klass.classes.version import KlassVersion
-from klass.requests.klass_requests import changes
-from klass.requests.klass_requests import classification_by_id
-from klass.requests.klass_types import ClassificationsByIdType
-from klass.requests.klass_types import VersionPartType
+from ..requests.klass_requests import changes
+from ..requests.klass_requests import classification_by_id
+from ..requests.klass_types import ClassificationsByIdType
+from ..requests.klass_types import Language
+from ..requests.klass_types import OptionalLanguage
+from ..requests.klass_types import VersionPartType
+from .codes import KlassCodes
+from .correspondence import KlassCorrespondence
+from .variant import KlassVariant
+from .variant import KlassVariantSearchByName
+from .version import KlassVersion
 
 
 class KlassClassification:
@@ -48,9 +53,9 @@ class KlassClassification:
         _links (dict): A dictionary containing the links to different possible endpoints using the classification.
 
     Args:
-        classification_id (str): The classification_id of the classification. For example: '36'
-        language (str): The language of the classification. "nb", "nn" or "en".
-        include_future (bool): Whether to include future versions of the classification.
+        classification_id: The classification_id of the classification. For example: '36'
+        language: The language of the classification. "nb", "nn" or "en".
+        include_future: Whether to include future versions of the classification.
 
     Raises:
         ValueError: If the language is not "no", "nb" or "en".
@@ -58,11 +63,14 @@ class KlassClassification:
     """
 
     def __init__(
-        self, classification_id: str, language: str = "nb", include_future: bool = False
+        self: Self,
+        classification_id: str | int,
+        language: Language = "nb",
+        include_future: bool = False,
     ) -> None:
         """Get the data for the classification from the API."""
         self.classification_id = classification_id
-        self.language = language
+        self.language: Language = language
         self.include_future = include_future
         result: ClassificationsByIdType = classification_by_id(
             classification_id, language=language, include_future=include_future
@@ -71,7 +79,7 @@ class KlassClassification:
         self.classificationType: str = result.get("classificationType", "")
         self.lastModified: str = result.get("lastModified", "")
         self.description: str = result.get("description", "")
-        self.primaryLanguage: str = result.get("primaryLanguage", "")
+        self.primaryLanguage: Language | Literal[""] = result.get("primaryLanguage", "")
         self.copyrighted: bool = result.get("copyrighted", True)
         self.includeShortName: bool = result.get("includeShortName", False)
         self.includeNotes: bool = result.get("includeNotes", False)
@@ -117,9 +125,9 @@ class KlassClassification:
 
     def get_version(
         self,
-        version_id: int = 0,
-        select_level: int = 0,
-        language: str = "",
+        version_id: int | None = None,
+        select_level: int | None = None,
+        language: OptionalLanguage = None,
         include_future: bool | None = None,
     ) -> KlassVersion:
         """Return a KlassVersion object of the classification based on ID.
@@ -128,10 +136,10 @@ class KlassClassification:
         If no ID is specified, will get the first version under the attribute .versions on this class.
 
         Args:
-            version_id (int): The version ID of the version.
-            select_level (int): The level of the version to keep in the data.
-            language (str): The language of the version. "nn", "nb" or "en".
-            include_future (bool): Whether to include future versions of the version.
+            version_id: The version ID of the version.
+            select_level: The level of the version to keep in the data.
+            language: The language of the version. "nn", "nb" or "en".
+            include_future: Whether to include future versions of the version.
 
         Returns:
             KlassVersion: A KlassVersion object of the specified ID.
@@ -140,7 +148,7 @@ class KlassClassification:
             version_id = sorted(self.versions, key=lambda x: x["validFrom"])[-1][
                 "version_id"
             ]
-        if language == "":
+        if not language:
             language = self.language
         if include_future is None:
             include_future = self.include_future
@@ -163,11 +171,11 @@ class KlassClassification:
         self,
         name: str,
         from_date: str,
-        to_date: str = "",
-        select_codes: str = "",
-        select_level: int = 0,
-        presentation_name_pattern: str = "",
-        language: str = "nb",
+        to_date: str | None = None,
+        select_codes: str | None = None,
+        select_level: int | None = None,
+        presentation_name_pattern: str | None = None,
+        language: Language = "nb",
         include_future: bool = False,
     ) -> KlassVariantSearchByName:
         """Get a KlassVariant by searching for its name under the Variants owned by the current classification.
@@ -177,16 +185,16 @@ class KlassClassification:
         redefine upper levels for some lower-level codes.
 
         Args:
-            name (str): The start of the name of the variant.
-            from_date (str): The start date of the time period. "YYYY-MM-DD".
-            to_date (str): The end date of the time period. "YYYY-MM-DD".
-            select_codes (str): Limit the result to codes matching this pattern.
+            name: The start of the name of the variant.
+            from_date: The start date of the time period. "YYYY-MM-DD".
+            to_date: The end date of the time period. "YYYY-MM-DD".
+            select_codes: Limit the result to codes matching this pattern.
                 See rules: https://data.ssb.no/api/klass/v1/api-guide.html#_selectcodes.
-            select_level (int): The level of the version to keep in the data.
-            presentation_name_pattern (str): Used to build an alternative presentation name for the codes.
+            select_level: The level of the version to keep in the data.
+            presentation_name_pattern: Used to build an alternative presentation name for the codes.
                 See rules: https://data.ssb.no/api/klass/v1/api-guide.html#_presentationnamepattern.
-            language (str): The language of the version. "nn", "nb" or "en".
-            include_future (bool): Whether to include future versions of the version.
+            language: The language of the version. "nn", "nb" or "en".
+            include_future: Whether to include future versions of the version.
 
         Returns:
             KlassVariantSearchByName: A KlassVariantSearchByName object based on the classification's ID
@@ -206,10 +214,10 @@ class KlassClassification:
 
     def get_correspondence_to(
         self,
-        target_classification_id: str,
+        target_classification_id: str | int,
         from_date: str,
-        to_date: str = "",
-        language: str = "",
+        to_date: str | None = None,
+        language: OptionalLanguage = None,
         include_future: bool | None = None,
     ) -> KlassCorrespondence:
         """Treats the current classification as a source of correspondences, specifying the target's ID and a date.
@@ -217,17 +225,17 @@ class KlassClassification:
         Returns a KlassCorrespondence object of the correspondences.
 
         Args:
-            target_classification_id (str): The classification ID of the target classification.
-            from_date (str): The start date of the time period. "YYYY-MM-DD".
-            to_date (str): The end date of the time period. "YYYY-MM-DD".
-            language (str): The language of the correspondences. "nn", "nb" or "en".
-            include_future (bool): Whether to include future correspondences.
+            target_classification_id: The classification ID of the target classification.
+            from_date: The start date of the time period. "YYYY-MM-DD".
+            to_date: The end date of the time period. "YYYY-MM-DD".
+            language: The language of the correspondences. "nn", "nb" or "en".
+            include_future: Whether to include future correspondences.
 
         Returns:
             KlassCorrespondence: A KlassCorrespondence object of the correspondences
             between the current classification and the target classification.
         """
-        if language == "":
+        if not language:
             language = self.language
         if include_future is None:
             include_future = self.include_future
@@ -242,32 +250,32 @@ class KlassClassification:
 
     def get_codes(
         self,
-        from_date: str = "",
-        to_date: str = "",
-        select_codes: str = "",
-        select_level: int = 0,
-        presentation_name_pattern: str = "",
-        language: str = "",
+        from_date: str | None = None,
+        to_date: str | None = None,
+        select_codes: str | None = None,
+        select_level: int | None = None,
+        presentation_name_pattern: str | None = None,
+        language: OptionalLanguage = None,
         include_future: bool | None = None,
     ) -> KlassCodes:
         """Return a KlassCodes object of the classification at a specific time or in a specific time range.
 
         Args:
-            from_date (str): The start date of the time period. "YYYY-MM-DD".
-            to_date (str): The end date of the time period. "YYYY-MM-DD".
-            select_codes (str): Limit the result to codes matching this pattern.
+            from_date: The start date of the time period. "YYYY-MM-DD".
+            to_date: The end date of the time period. "YYYY-MM-DD".
+            select_codes: Limit the result to codes matching this pattern.
                 See rules: https://data.ssb.no/api/klass/v1/api-guide.html#_selectcodes.
-            select_level (int): The level of the version to keep in the data.
-            presentation_name_pattern (str): Used to build an alternative presentation name for the codes.
+            select_level: The level of the version to keep in the data.
+            presentation_name_pattern: Used to build an alternative presentation name for the codes.
                 See rules: https://data.ssb.no/api/klass/v1/api-guide.html#_presentationnamepattern.
-            language (str): The language of the version. "nn", "nb" or "en".
-            include_future (bool): Whether to include future versions of the version.
+            language: The language of the version. "nn", "nb" or "en".
+            include_future: Whether to include future versions of the version.
 
         Returns:
             KlassCodes: A KlassCodes object of the classification at a specific time or in a specific time range.
         """
         # If not passed to method, grab these from the Classification
-        if language == "":
+        if not language:
             language = self.language
         if include_future is None:
             include_future = self.include_future
@@ -286,8 +294,8 @@ class KlassClassification:
     def get_changes(
         self,
         from_date: str,
-        to_date: str = "",
-        language: str = "nb",
+        to_date: str | None = None,
+        language: OptionalLanguage = "nb",
         include_future: bool = False,
     ) -> pd.DataFrame:
         """Return a dataframe of the classification at a specific time or in a specific time range.
@@ -296,10 +304,10 @@ class KlassClassification:
         but only what has changed since the last update or within the time range.
 
         Args:
-            from_date (str): The start date of the time period. "YYYY-MM-DD".
-            to_date (str): The end date of the time period. "YYYY-MM-DD".
-            language (str): The language of the version. "nn", "nb" or "en".
-            include_future (bool): Whether to include future versions of the version.
+            from_date: The start date of the time period. "YYYY-MM-DD".
+            to_date: The end date of the time period. "YYYY-MM-DD".
+            language: The language of the version. "nn", "nb" or "en".
+            include_future: Whether to include future versions of the version.
 
         Returns:
             pd.DataFrame: A pandas DataFrame of the changes in the classification at a specific time
@@ -313,7 +321,7 @@ class KlassClassification:
             include_future=include_future,
         )
 
-    def get_latest_variant_by_name(self, variant_name: str) -> KlassVariant | None:
+    def get_latest_variant_by_name(self, variant_name: str) -> KlassVariant:
         """Attempt to get a single variant from the classification using a search string.
 
         Args:
@@ -323,7 +331,7 @@ class KlassClassification:
             ValueError: If the string is not specific enough, and zero, or more than a single variant is found.
 
         Returns:
-            KlassVariant | None: The single variant we found with the search string. Or None if we found no matches.
+            KlassVariant: The single variant we found with the search string. Raises if we found no matches.
         """
         version = self.get_version()
         variants = version.variants_simple()
@@ -346,7 +354,7 @@ class KlassClassification:
 
     def join_all_variants_correspondences_on_data(
         self,
-        version_id: int = 0,
+        version_id: int | None = None,
         shortname_len: int = 3,
         data_left: pd.DataFrame | None = None,
         code_col_name: str = "code",
@@ -357,7 +365,7 @@ class KlassClassification:
         Can be quite slow, as it is doing a request to the KLASS-API for every variant and Correspondence.
 
         Args:
-            version_id: If you want, specify the ID of the version. If 0, will get the "latest" version for the classification.
+            version_id: If you want, specify the ID of the version. If None, will get the "latest" version for the classification.
             shortname_len: Amount of words from the correspondences that the new column names will be constructed from.
             data_left: A dataframe containing a column to join all the correspondences on. If None will get data from the version.
             code_col_name: The column in the data to join the code on.

{ssb_klass_python-1.0.1 → ssb_klass_python-1.0.2}/src/klass/classes/codes.py

@@ -4,8 +4,9 @@ from datetime import datetime
 import pandas as pd
 from typing_extensions import Self
 
-from klass.requests.klass_requests import codes
-from klass.requests.klass_requests import codes_at
+from ..requests.klass_requests import codes
+from ..requests.klass_requests import codes_at
+from ..requests.klass_types import Language
 
 
 class KlassCodes:
@@ -20,14 +21,14 @@ class KlassCodes:
         to_date (str): The end date of the time period. "YYYY-MM-DD".
 
     Args:
-        classification_id (str): The classification ID.
-        from_date (str): The start date of the time period. "YYYY-MM-DD".
-        to_date (str): The end date of the time period. "YYYY-MM-DD".
-        select_codes (str): A list of codes to be selected.
-        select_level (int): The level to keep in the data.
-        presentation_name_pattern (str): A pattern for filtering the code names.
-        language (str): The language of the code names. Defaults to "nb".
-        include_future (bool): Whether to include future codes. Defaults to False.
+        classification_id: The classification ID.
+        from_date: The start date of the time period. "YYYY-MM-DD".
+        to_date: The end date of the time period. "YYYY-MM-DD".
+        select_codes: A list of codes to be selected.
+        select_level: The level to keep in the data.
+        presentation_name_pattern: A pattern for filtering the code names.
+        language: The language of the code names. Defaults to "nb".
+        include_future: Whether to include future codes. Defaults to False.
 
     Raises:
         ValueError: If from_date or to_date is not a valid date or date-string YYYY-MM-DD.
@@ -40,13 +41,13 @@ class KlassCodes:
 
     def __init__(
         self,
-        classification_id: str = "",
-        from_date: str = "",
-        to_date: str = "",
-        select_codes: str = "",
-        select_level: int = 0,
-        presentation_name_pattern: str = "",
-        language: str = "nb",
+        classification_id: str | int,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        select_codes: str | None = None,
+        select_level: int | None = None,
+        presentation_name_pattern: str | None = None,
+        language: Language = "nb",
         include_future: bool = False,
     ) -> None:
         """Get the data from the KLASS-api belonging to the code-list."""
@@ -58,7 +59,7 @@ class KlassCodes:
         self.select_codes = select_codes
         self.select_level = select_level
         self.presentation_name_pattern = presentation_name_pattern
-        self.language = language
+        self.language: Language = language
         self.include_future = include_future
         self.get_codes()
 
@@ -97,16 +98,16 @@ class KlassCodes:
 
     def change_dates(
         self,
-        from_date: str = "",
+        from_date: str | None = None,
         to_date: str = "",
         include_future: bool | None = None,
     ) -> Self:
         """Change the dates of the codelist and get the data again based on new dates.
 
         Args:
-            from_date (str): The start date of the time period. "YYYY-MM-DD".
-            to_date (str): The end date of the time period. "YYYY-MM-DD".
-            include_future (bool): Whether to include future codes.
+            from_date: The start date of the time period. "YYYY-MM-DD".
+            to_date: The end date of the time period. "YYYY-MM-DD".
+            include_future: Whether to include future codes.
 
         Returns:
             self (KlassSearchFamilies): Returns self to make the method more easily chainable.
@@ -128,7 +129,7 @@ class KlassCodes:
         the date specified by self.from_date.
 
         Args:
-            raise_on_empty_data (bool): Whether to raise an error if the returned dataframe is empty. Defaults to True.
+            raise_on_empty_data: Whether to raise an error if the returned dataframe is empty. Defaults to True.
 
         Returns:
             self (KlassSearchFamilies): Returns self to make the method more easily chainable.
@@ -166,17 +167,17 @@ class KlassCodes:
     def to_dict(
         self,
         key: str = "code",
-        value: str = "",  # default is "name" if not set
-        other: str = "",
+        value: str | None = None,  # default is "name" if not set
+        other: str | None = None,
     ) -> dict[str, str] | defaultdict[str, str]:
         """Extract two columns from the data, turning them into a dict.
 
         If you specify a value for "other", returns a defaultdict instead.
 
         Args:
-            key (str): The name of the column with the values you want as keys.
-            value (str): The name of the column with the values you want as values in your dict.
-            other (str): If key is missing from dict, return this value instead, if you specify an OTHER-value.
+            key: The name of the column with the values you want as keys.
+            value: The name of the column with the values you want as values in your dict.
+            other: If key is missing from dict, return this value instead, if you specify an OTHER-value.
 
         Returns:
             dict | defaultdict: The extracted columns as a dict or defaultdict.
@@ -201,7 +202,7 @@ class KlassCodes:
         First envisioned by @mfmssb
 
         Args:
-            keep (list[str]): The start of the names of the columns you want to keep when done.
+            keep: The start of the names of the columns you want to keep when done.
                 Default is ["code", "name"], but other possibilities are "presentationName",
                 "level", "shortName", "validTo", "validFrom", and "notes".
 

{ssb_klass_python-1.0.1 → ssb_klass_python-1.0.2}/src/klass/classes/correspondence.py

@@ -5,11 +5,13 @@ from datetime import date
 import dateutil.parser
 import pandas as pd
 from typing_extensions import Self
+from typing_extensions import overload
 
-from klass.requests.klass_requests import correspondence_table_by_id
-from klass.requests.klass_requests import corresponds
-from klass.requests.klass_types import CorrespondsType
-from klass.requests.klass_types import T_correspondanceMaps
+from ..requests.klass_requests import correspondence_table_by_id
+from ..requests.klass_requests import corresponds
+from ..requests.klass_types import CorrespondsType
+from ..requests.klass_types import Language
+from ..requests.klass_types import T_correspondanceMaps
 
 
 class KlassCorrespondence:
@@ -35,26 +37,52 @@ class KlassCorrespondence:
         include_future (bool): If the correspondence should include future correspondences.
 
     Args:
-        correspondence_id (str): The ID of the correspondence.
-        source_classification_id (str): The ID of the source classification.
-        target_classification_id (str): The ID of the target classification.
-        from_date (str): The start date of the correspondence.
-        to_date (str, optional): The end date of the correspondence.
-        contain_quarter (int): The number of quarters the correspondence should contain,
+        correspondence_id: The ID of the correspondence.
+        source_classification_id: The ID of the source classification.
+        target_classification_id: The ID of the target classification.
+        from_date: The start date of the correspondence.
+        to_date: The end date of the correspondence.
+        contain_quarter: The number of quarters the correspondence should contain,
             this replaces the to_date during initialization.
-        language (str): The language of the correspondence. "nb", "nn" or "en".
-        include_future (bool): If the correspondence should include future correspondences.
+        language: The language of the correspondence. "nb", "nn" or "en".
+        include_future: If the correspondence should include future correspondences.
     """
 
+    @overload
     def __init__(
-        self,
-        correspondence_id: str = "",
-        source_classification_id: str = "",
-        target_classification_id: str = "",
-        from_date: str = "",
-        to_date: str = "",
+        self: Self,
+        correspondence_id: str | int = ...,
+        source_classification_id: None = ...,
+        target_classification_id: None = ...,
+        from_date: None = ...,
+        to_date: None = ...,
+        contain_quarter: int = ...,
+        language: Language = ...,
+        include_future: bool = ...,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self: Self,
+        correspondence_id: None = ...,
+        source_classification_id: str | int = ...,
+        target_classification_id: str | int = ...,
+        from_date: str = ...,
+        to_date: str | None = ...,
+        contain_quarter: int = ...,
+        language: Language = ...,
+        include_future: bool = ...,
+    ) -> None: ...
+
+    def __init__(
+        self: Self,
+        correspondence_id: str | int | None = None,
+        source_classification_id: str | int | None = None,
+        target_classification_id: str | int | None = None,
+        from_date: str | None = None,
+        to_date: str | None = None,
         contain_quarter: int = 0,
-        language: str = "nb",
+        language: Language = "nb",
         include_future: bool = False,
     ) -> None:
         """Get the correspondence-data from the API."""
@@ -64,7 +92,7 @@ class KlassCorrespondence:
         self.from_date = from_date
         self.to_date = to_date
         self.contain_quarter = contain_quarter
-        self.language = language
+        self.language: Language = language
         self.include_future = include_future
 
         self.get_correspondence()
@@ -166,8 +194,15 @@ class KlassCorrespondence:
         Uses the attribute "contain_quarter" to determine which quarter to use.
 
         Returns:
-            str: The last date of the quarter.
+            The last date of the quarter.
+
+        Raises:
+            ValueError: if from date is missing
         """
+        if not self.from_date:
+            raise ValueError(
+                "Can't calculate the last date of the quarter without from_date"
+            )
         from_date = dateutil.parser.parse(self.from_date)
         year = from_date.year
         last_month_of_quarter = 3 * self.contain_quarter
@@ -180,9 +215,9 @@ class KlassCorrespondence:
         self,
         key: str = "sourceCode",
         value: str = "targetCode",
-        other: str = "",
+        other: str | None = None,
         remove_na: bool = True,
-        select_level: int = 0,
+        select_level: int | None = None,
     ) -> dict[str, str | None] | defaultdict[str, str | None]:
         """Extract two columns from the data, turning them into a dict.
 
@@ -192,9 +227,9 @@ class KlassCorrespondence:
         'targetCode', 'targetName', 'targetShortName', 'validFrom', 'validTo'.
 
         Args:
-            key (str): The name of the column with the values you want as keys.
-            value (str): The name of the column with the values you want as values in your dict.
-            other (str): The value to use for keys that don't exist in the data.
+            key: The name of the column with the values you want as keys.
+            value: The name of the column with the values you want as values in your dict.
+            other: The value to use for keys that don't exist in the data.
             remove_na: Set to False if you want to keep empty mappings over the key and value columns. Empty is defined as empty strings or NA-types.
             select_level: Keep only a specific level defines the variants codes / groups.
 

{ssb_klass_python-1.0.1 → ssb_klass_python-1.0.2}/src/klass/classes/family.py

@@ -1,7 +1,7 @@
-from klass.classes.classification import KlassClassification
-from klass.requests.klass_requests import classificationfamilies_by_id
-from klass.requests.klass_types import ClassificationFamiliesByIdType
-from klass.requests.klass_types import ClassificationPartWithType
+from ..requests.klass_requests import classificationfamilies_by_id
+from ..requests.klass_types import ClassificationFamiliesByIdType
+from ..requests.klass_types import ClassificationPartWithType
+from .classification import KlassClassification
 
 
 class KlassFamily:
@@ -17,10 +17,10 @@ class KlassFamily:
         _links (dict): A dictionary of API links referencing itself.
 
     Args:
-        family_id (str): The ID of the family.
+        family_id: The ID of the family.
     """
 
-    def __init__(self, family_id: str) -> None:
+    def __init__(self, family_id: str | int) -> None:
         """Get the family data from the klass-api, setting it as attributes on the object."""
         self.family_id = family_id
         # Setting for mypy
@@ -57,11 +57,13 @@ And contains the following classifications:
         """Representation of the object, and how to recreate it."""
         return f"KlassFamily({self.family_id})"
 
-    def get_classification(self, classification_id: str = "") -> KlassClassification:
+    def get_classification(
+        self, classification_id: str | int | None = None
+    ) -> KlassClassification:
         """Get a classification from the family.
 
         Args:
-            classification_id (str): The ID of the classification.
+            classification_id: The ID of the classification.
                 If not given, the first classification in the family is returned based on its ID.
 
         Returns: