ssb-klass-python 1.0.3__tar.gz

ssb_klass_python-1.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2023 Statistics Norway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ssb_klass_python-1.0.3/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: ssb-klass-python
+Version: 1.0.3
+Summary: A Python package built on top of KLASS's API for retrieving classifications, codes, correspondences etc.
+License-Expression: MIT
+License-File: LICENSE
+Author: Carl Corneil
+Author-email: ssb-pythonistas <ssb-pythonistas@ssb.no>
+Requires-Python: >=3.11,<4
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: ipython (<9)
+Requires-Dist: ipywidgets (>=8.0.6)
+Requires-Dist: pandas (>=1.5.3)
+Requires-Dist: python-dateutil (>=2.8.2)
+Requires-Dist: requests (>=2.31.0)
+Requires-Dist: toml (>=0.10.2)
+Requires-Dist: typing-extensions (>=4.12.2)
+Project-URL: Documentation, https://statisticsnorway.github.io/ssb-klass-python
+Project-URL: Homepage, https://github.com/statisticsnorway/ssb-klass-python
+Project-URL: Repository, https://github.com/statisticsnorway/ssb-klass-python
+Description-Content-Type: text/markdown
+
+# ssb-klass-python / KLASS
+[![PyPI](https://img.shields.io/pypi/v/ssb-klass-python.svg)][pypi status]
+[![Status](https://img.shields.io/pypi/status/ssb-klass-python.svg)][pypi status]
+[![Python Version](https://img.shields.io/pypi/pyversions/ssb-klass-python)][pypi status]
+[![License](https://img.shields.io/pypi/l/ssb-klass-python)][license]
+
+[![Documentation](https://github.com/statisticsnorway/ssb-klass-python/actions/workflows/docs.yml/badge.svg)][documentation]
+[![Tests](https://github.com/statisticsnorway/ssb-klass-python/actions/workflows/tests.yml/badge.svg)][tests]
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=statisticsnorway_ssb-klass-python&metric=coverage)][sonarcov]
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=statisticsnorway_ssb-klass-python&metric=alert_status)][sonarquality]
+
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)][pre-commit]
+[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)][black]
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)][poetry]
+
+[pypi status]: https://pypi.org/project/ssb-klass-python/
+[documentation]: https://statisticsnorway.github.io/ssb-klass-python
+[tests]: https://github.com/statisticsnorway/ssb-klass-python/actions?workflow=Tests
+
+[sonarcov]: https://sonarcloud.io/summary/overall?id=statisticsnorway_ssb-klass-python
+[sonarquality]: https://sonarcloud.io/summary/overall?id=statisticsnorway_ssb-klass-python
+[pre-commit]: https://github.com/pre-commit/pre-commit
+[black]: https://github.com/psf/black
+[poetry]: https://python-poetry.org/
+A Python package built on top of Statistics Norway's code- and classification-system "KLASS". \
+The package aims to make Klass's API for retrieving data easier to use by re-representing Klass's internal hierarchy as python-classes. Containing methods for easier traversal down, search classes and widgets, reasonable defaults to parameters etc.
+Where data is possible to fit into pandas DataFrames, this will be preferred, but hiererachical data / objects containing metadata will be kept as json / dict structure.
+
+
+## Installing
+The package is available on Pypi, and can be installed by for example poetry like this:
+```bash
+poetry add ssb-klass-python
+```
+
+
+## Example usages
+
+
+### Getting started
+```python
+from klass import search_classification
+# Opens a ipywidget in notebooks for searching for classifications and copying code, to get started
+search_classification(no_dupes=True)
+```
+![The GUI available through the search_classification function](GUI.png)
+
+
+
+### Getting a classification directly
+```python
+from klass import get_classification # Import the utility-function
+nus = get_classification(36)
+```
+
+```python
+# Does the same as the code above, but does not shy away from using the class directly
+from klass import KlassClassification # Import the class for KlassClassifications
+nus = KlassClassification(36)  # Use ID for classification
+```
+
+When you have the classification stored in an object, you can "dig into" the API from there.
+```python
+codes = nus.get_codes() # codes from current date
+print(codes)
+codes.data  # Pandas dataframe available under the .data attribute
+```
+
+
+From searching through "families", down to a specific codelist
+```python
+from klass import KlassSearchFamilies
+search = KlassSearchFamilies(360)
+print(search)
+>>> "Family ID: 20 - Utdanning - Number of classifications: 5"
+utdanning = search.get_family(20)
+print(utdanning)
+>>> "The Klass Family "Utdanning" has id 20."
+>>> "And contains the following classifications:"
+>>>  "36: Standard for utdanningsgruppering (NUS)"
+nus = utdanning.get_classification(36)
+print(nus)
+>>> "Classification 36: Standard for utdanningsgruppering (NUS)..."
+nus_codes = nus.get_codes("2023-01-01")
+print(nus_codes)
+>>> "Codelist for classification: 36"
+>>> " From date: 2023-01-01"
+nus_codes.data  # A pandas dataframe
+```
+
+
+For more examples check out the demo-notebooks in the demo/ folder in the repo.
+
+
+
+## Technical notes
+Documentation for the [endpoints we are using can be found on Statistics Norways pages.](https://data.ssb.no/api/klass/v1/api-guide.html)
+
+Technical architecture of the API we are interacting with is detailed in [Statistics Norway's **internal** wiki](https://wiki.ssb.no/display/KP/Teknisk+arkitektur#Tekniskarkitektur-GSIM).
+
+This project has been migrated to follow the [SSB PyPI Template] from [Statistics Norway].
+
+[statistics norway]: https://www.ssb.no/en
+[pypi]: https://pypi.org/
+[ssb pypi template]: https://github.com/statisticsnorway/ssb-pypitemplate
+[file an issue]: https://github.com/statisticsnorway/ssb-klass-python/issues
+[pip]: https://pip.pypa.io/
+
+<!-- github-only -->
+
+[license]: https://github.com/statisticsnorway/ssb-klass-python/blob/main/LICENSE
+[contributor guide]: https://github.com/statisticsnorway/ssb-klass-python/blob/main/CONTRIBUTING.md
+[reference guide]: https://statisticsnorway.github.io/ssb-klass-python/reference.html
+

ssb_klass_python-1.0.3/README.md

@@ -0,0 +1,114 @@
+# ssb-klass-python / KLASS
+[![PyPI](https://img.shields.io/pypi/v/ssb-klass-python.svg)][pypi status]
+[![Status](https://img.shields.io/pypi/status/ssb-klass-python.svg)][pypi status]
+[![Python Version](https://img.shields.io/pypi/pyversions/ssb-klass-python)][pypi status]
+[![License](https://img.shields.io/pypi/l/ssb-klass-python)][license]
+
+[![Documentation](https://github.com/statisticsnorway/ssb-klass-python/actions/workflows/docs.yml/badge.svg)][documentation]
+[![Tests](https://github.com/statisticsnorway/ssb-klass-python/actions/workflows/tests.yml/badge.svg)][tests]
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=statisticsnorway_ssb-klass-python&metric=coverage)][sonarcov]
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=statisticsnorway_ssb-klass-python&metric=alert_status)][sonarquality]
+
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)][pre-commit]
+[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)][black]
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)][poetry]
+
+[pypi status]: https://pypi.org/project/ssb-klass-python/
+[documentation]: https://statisticsnorway.github.io/ssb-klass-python
+[tests]: https://github.com/statisticsnorway/ssb-klass-python/actions?workflow=Tests
+
+[sonarcov]: https://sonarcloud.io/summary/overall?id=statisticsnorway_ssb-klass-python
+[sonarquality]: https://sonarcloud.io/summary/overall?id=statisticsnorway_ssb-klass-python
+[pre-commit]: https://github.com/pre-commit/pre-commit
+[black]: https://github.com/psf/black
+[poetry]: https://python-poetry.org/
+A Python package built on top of Statistics Norway's code- and classification-system "KLASS". \
+The package aims to make Klass's API for retrieving data easier to use by re-representing Klass's internal hierarchy as python-classes. Containing methods for easier traversal down, search classes and widgets, reasonable defaults to parameters etc.
+Where data is possible to fit into pandas DataFrames, this will be preferred, but hiererachical data / objects containing metadata will be kept as json / dict structure.
+
+
+## Installing
+The package is available on Pypi, and can be installed by for example poetry like this:
+```bash
+poetry add ssb-klass-python
+```
+
+
+## Example usages
+
+
+### Getting started
+```python
+from klass import search_classification
+# Opens a ipywidget in notebooks for searching for classifications and copying code, to get started
+search_classification(no_dupes=True)
+```
+![The GUI available through the search_classification function](GUI.png)
+
+
+
+### Getting a classification directly
+```python
+from klass import get_classification # Import the utility-function
+nus = get_classification(36)
+```
+
+```python
+# Does the same as the code above, but does not shy away from using the class directly
+from klass import KlassClassification # Import the class for KlassClassifications
+nus = KlassClassification(36)  # Use ID for classification
+```
+
+When you have the classification stored in an object, you can "dig into" the API from there.
+```python
+codes = nus.get_codes() # codes from current date
+print(codes)
+codes.data  # Pandas dataframe available under the .data attribute
+```
+
+
+From searching through "families", down to a specific codelist
+```python
+from klass import KlassSearchFamilies
+search = KlassSearchFamilies(360)
+print(search)
+>>> "Family ID: 20 - Utdanning - Number of classifications: 5"
+utdanning = search.get_family(20)
+print(utdanning)
+>>> "The Klass Family "Utdanning" has id 20."
+>>> "And contains the following classifications:"
+>>>  "36: Standard for utdanningsgruppering (NUS)"
+nus = utdanning.get_classification(36)
+print(nus)
+>>> "Classification 36: Standard for utdanningsgruppering (NUS)..."
+nus_codes = nus.get_codes("2023-01-01")
+print(nus_codes)
+>>> "Codelist for classification: 36"
+>>> " From date: 2023-01-01"
+nus_codes.data  # A pandas dataframe
+```
+
+
+For more examples check out the demo-notebooks in the demo/ folder in the repo.
+
+
+
+## Technical notes
+Documentation for the [endpoints we are using can be found on Statistics Norways pages.](https://data.ssb.no/api/klass/v1/api-guide.html)
+
+Technical architecture of the API we are interacting with is detailed in [Statistics Norway's **internal** wiki](https://wiki.ssb.no/display/KP/Teknisk+arkitektur#Tekniskarkitektur-GSIM).
+
+This project has been migrated to follow the [SSB PyPI Template] from [Statistics Norway].
+
+[statistics norway]: https://www.ssb.no/en
+[pypi]: https://pypi.org/
+[ssb pypi template]: https://github.com/statisticsnorway/ssb-pypitemplate
+[file an issue]: https://github.com/statisticsnorway/ssb-klass-python/issues
+[pip]: https://pip.pypa.io/
+
+<!-- github-only -->
+
+[license]: https://github.com/statisticsnorway/ssb-klass-python/blob/main/LICENSE
+[contributor guide]: https://github.com/statisticsnorway/ssb-klass-python/blob/main/CONTRIBUTING.md
+[reference guide]: https://statisticsnorway.github.io/ssb-klass-python/reference.html

ssb_klass_python-1.0.3/pyproject.toml

@@ -0,0 +1,172 @@
+[project]
+name = "ssb-klass-python"
+version = "1.0.3"
+description = "A Python package built on top of KLASS's API for retrieving classifications, codes, correspondences etc."
+authors = [{name="Carl Corneil", email="ssb-pythonistas <ssb-pythonistas@ssb.no>"}, {name = "Statistics Norway" }]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.11,<4"
+
+dependencies = [
+    "python-dateutil >=2.8.2",
+    "toml >=0.10.2",
+    "ipywidgets >=8.0.6",
+    "pandas >=1.5.3",
+    "requests >=2.31.0",
+    "ipython <9",
+    "typing-extensions >=4.12.2",
+
+]
+
+[project.urls]
+homepage = "https://github.com/statisticsnorway/ssb-klass-python"
+repository = "https://github.com/statisticsnorway/ssb-klass-python"
+documentation = "https://statisticsnorway.github.io/ssb-klass-python"
+
+
+[tool.poetry]
+packages = [{ include = "klass", from = "src" }]
+classifiers = ["Development Status :: 4 - Beta"]
+requires-poetry = ">=2.0"
+
+[tool.poetry.urls]
+Changelog = "https://github.com/statisticsnorway/ssb-klass-python/releases"
+
+
+
+[tool.poetry.group.dev.dependencies]
+pygments = ">=2.10.0"
+black = { extras = ["jupyter"], version = ">=24.3.0" }
+coverage = { extras = ["toml"], version = ">=6.2" }
+darglint = ">=1.8.1"
+furo = ">=2021.11.12"
+mypy = ">=0.930"
+ipykernel = ">=6.15.3"
+pre-commit = ">=2.20.0"
+pre-commit-hooks = ">=4.4.0"
+pytest = ">=6.2.5"
+pytest-cov = ">=4.0.0"
+pyproject-flake8 = ">=5.0.4.post1"
+nox = ">=2023.4.22"
+nox-poetry = ">=1.0.3"
+ruff = ">=0.0.284"
+sphinx = ">=6.2.1"
+sphinx-autobuild = ">=2021.3.14"
+sphinx-autodoc-typehints = ">=1.24.0"
+sphinx-click = ">=3.0.2"
+typeguard = ">=2.13.3"
+xdoctest = { extras = ["colors"], version = ">=0.15.10" }
+myst-parser = { version = ">=0.16.1" }
+deptry = ">=0.23.0"
+# Stubs for Mypy
+pandas-stubs = ">=2.1.1.230928"
+types-requests = ">=2.31.0.10"
+types-python-dateutil = ">=2.8.19.14"
+types-toml = ">=0.10.8.7"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+
+[tool.coverage.paths]
+source = ["src", "*/site-packages"]
+tests = ["tests", "*/tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["klass", "tests"]
+relative_files = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 50
+
+[tool.mypy]
+strict = true
+warn_unreachable = true
+pretty = true
+show_column_numbers = true
+show_error_context = true
+exclude = ["tests", "docs", "noxfile.py"]
+explicit_package_bases = true
+
+[[tool.mypy.overrides]]
+module = ["ipywidgets.*", "argcomplete.*"]
+ignore_missing_imports = true
+
+[tool.ruff]
+force-exclude = true     # Apply excludes to pre-commit
+show-fixes = true
+src = ["src", "tests"]
+target-version = "py310" # Minimum Python version supported
+
+include = ["*.py", "*.pyi", "**/pyproject.toml", "*.ipynb"]
+extend-exclude = [
+    "__pycache__",
+    "old",
+    ".ipynb_checkpoints",
+    "noxfile.py",
+    "docs/conf.py",
+]
+
+# Ruff rules may be customized as desired: https://docs.astral.sh/ruff/rules/
+[tool.ruff.lint]
+select = [
+    "A",   # prevent using keywords that clobber python builtins
+    "ANN", # check type annotations
+    "B",   # bugbear: security warnings
+    "D",   # documentation
+    "E",   # pycodestyle
+    "F",   # pyflakes
+    "ISC", # implicit string concatenation
+    "I",   # sort imports
+    "UP",  # alert you when better syntax is available in your python version
+    "RUF", # the ruff developer's own rules
+]
+ignore = [
+    "ANN202", # Don't requiere return type annotation for private functions.
+    "ANN401", # Allow type annotation with type Any.
+    "D100",   # Supress undocumented-public-module. Only doc of public api required.
+    "E402",   # Supress module-import-not-at-top-of-file, needed in jupyter notebooks.
+    "E501",   # Supress line-too-long warnings: trust black's judgement on this one.
+]
+
+[tool.ruff.lint.isort]
+force-single-line = true
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15
+
+[tool.ruff.lint.pydocstyle]
+convention = "google" # You can also use "numpy".
+
+[tool.ruff.lint.pep8-naming]
+classmethod-decorators = [
+    "classmethod",
+    "validator",
+    "root_validator",
+    "pydantic.validator",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"*/__init__.py" = ["F401"]
+"**/tests/*" = [
+    "ANN001", # type annotations don't add value for test functions
+    "ANN002", # type annotations don't add value for test functions
+    "ANN003", # type annotations don't add value for test functions
+    "ANN201", # type annotations don't add value for test functions
+    "ANN204", # type annotations don't add value for test functions
+    "ANN205", # type annotations don't add value for test functions
+    "ANN206", # type annotations don't add value for test functions
+    "D100",   # docstrings are overkill for test functions
+    "D101",
+    "D102",
+    "D103",
+    "D100",
+    "S101",   # asserts are encouraged in pytest
+]
+"demo/*.py" = ["B018"] # Ignore the useless expressions in the notebooks
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

ssb_klass_python-1.0.3/src/klass/__init__.py

@@ -0,0 +1,97 @@
+"""A Python package built on top of Statistics Norway's code- and classification-system "KLASS".
+
+The package aims to make Klass's API for retrieving data easier to use by re-representing Klass's internal hierarchy as python-classes.
+Containing methods for easier traversal down, search classes and widgets, reasonable defaults to parameters etc.
+Where data is possible to fit into pandas DataFrames, this will be preferred, but hirerachical data will be kept as json / dict structure.
+"""
+
+import importlib
+import importlib.metadata
+
+import toml
+
+
+def _try_getting_pyproject_toml(e: Exception | None = None) -> str:
+    if e is None:
+        passed_excep: Exception = Exception("")
+    else:
+        passed_excep = e
+    try:
+        version: str = toml.load("pyproject.toml")["tool"]["poetry"]["version"]
+        return version
+    except Exception as e:
+        version_missing: str = "0.0.0"
+        print(
+            f"Error from ssb-klass-pythons __init__, not able to get version-number, setting it to {version_missing}: {passed_excep}"
+        )
+        return version_missing
+
+
+# Gets the installed version from pyproject.toml, then there is no need to update this file
+try:
+    __version__ = importlib.metadata.version("ssb-klass-python")
+except importlib.metadata.PackageNotFoundError as e:
+    __version__ = _try_getting_pyproject_toml(e)
+
+
+from klass.classes.classification import KlassClassification
+from klass.classes.codes import KlassCodes
+from klass.classes.correspondence import KlassCorrespondence
+from klass.classes.family import KlassFamily
+from klass.classes.search import KlassSearchClassifications
+from klass.classes.search import KlassSearchFamilies
+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_requests import classification_search
+from klass.requests.klass_requests import classificationfamilies
+from klass.requests.klass_requests import classificationfamilies_by_id
+from klass.requests.klass_requests import classifications
+from klass.requests.klass_requests import codes
+from klass.requests.klass_requests import codes_at
+from klass.requests.klass_requests import correspondence_table_by_id
+from klass.requests.klass_requests import corresponds
+from klass.requests.klass_requests import corresponds_at
+from klass.requests.klass_requests import variant
+from klass.requests.klass_requests import variant_at
+from klass.requests.klass_requests import variants_by_id
+from klass.requests.klass_requests import version_by_id
+from klass.requests.sections import sections_dict
+from klass.requests.sections import sections_list
+from klass.utility.classification import get_classification
+from klass.utility.codes import get_codes
+from klass.widgets.search_ipywidget import search_classification
+
+__all__ = [
+    "KlassClassification",
+    "KlassCodes",
+    "KlassCorrespondence",
+    "KlassFamily",
+    "KlassSearchClassifications",
+    "KlassSearchFamilies",
+    "KlassVariant",
+    "KlassVariantSearchByName",
+    "KlassVersion",
+    "changes",
+    "classification_by_id",
+    "classification_search",
+    "classificationfamilies",
+    "classificationfamilies_by_id",
+    "classifications",
+    "codes",
+    "codes_at",
+    "correspondence_table_by_id",
+    "corresponds",
+    "corresponds_at",
+    "get_classification",
+    "get_codes",
+    "search_classification",
+    "sections_dict",
+    "sections_list",
+    "variant",
+    "variant_at",
+    "variants_by_id",
+    "version_by_id",
+]

ssb_klass_python-1.0.3/src/klass/classes/__init__.py

@@ -0,0 +1,9 @@
+"""The classes sub-module contains the actual classes the user should interact with.
+
+They call loose get-request-functions in the requests-module under initialization.
+Populating their attributes with metadata and data.
+Traversing down through a hierarchy of Family > Classification > Version (classification at time) > Codelist is possible.
+Traversing upwards is harder, as the API does not refer to parents of objects (would be nice if it did).
+You can also traverse sideways to "correspondences" which exist as edge-objects between two classification-versions.
+And get "variants", which are "alternative groupings" of codelists, belonging to versions.
+"""