SSB Kostra Python

Features

Oppsummering

• Denne pakken er til bruk for KOSTRA-brukere og gjenskaper noen av funksjonene dere var vant med fra KOMPIS. Disse er ikke like smidige som dem som var tilgjengelige i KOMPIS, men de utfører i stor grad de samme oppgavene, og med litt tilvenning vil dere forhåpentligvis slippe å lage helt egne funksjoner for de vanligste operasjonene. I avsnittet under forklares hva funksjonene gjør.

Funksjonene

Eksempelark

Du finner eksempelark på ssb-kostra-python/examples/. Der kan du kjøre gjennom funksjonene for å se hvordan det kan gjøres.

Programvarekrav

For å bruke ssb-kostra-python må prosjektet ditt bruke:

• Python 3.12 eller nyere
• Poetry for håndtering av pakker og avhengigheter

Du kan kontrollere hvilken Python-versjon du bruker ved å skrive følgende i terminalen:

python --version

Tilganger til fellesbøtter

Funksjonene henter filer fra fellesbøtter hos S312 Befolkningsstatistikk og S212 Offentlige finanser.

Hos S312 trenger du tilgang til:

folketall ---> ssb-bef-statistikk-data-delt-folketall-prod

Teamet som deler bøtten med deg er bef-statistikk. Kortnavnet på delt-bøtten er folketall. Dette må du angi når du åpner en ny tjeneste og skal ha tilgang til de delte filene.

Hos S212 trenger du tilgang til:

kostra-befolkning-delt ---> ssb-off-fin-data-delt-kostra-befolkning-delt-prod

Teamet som deler bøtten med deg er off-fin. Kortnavnet på delt-bøtten er kostra-befolkning-delt. Dette må du angi når du åpner en ny tjeneste og skal ha tilgang til de delte filene.

Installasjon

Pakken installeres med Poetry. Kjør følgende kommando i terminalen fra prosjektet der du ønsker å bruke pakken:

poetry add ssb-kostra-python

Du kan kontrollere om pakken er installert, og hvilken versjon du har, med:

poetry show ssb-kostra-python

Importere pakken

Merk at navnet som brukes når pakken installeres, og navnet som brukes når pakken importeres i Python, er litt forskjellige.

Pakken installeres med:

poetry add ssb-kostra-python

Men i Python brukes understrek (_) i stedet for bindestrek (-):

import ssb_kostra_python

Dette vil altså ikke fungere:

import ssb-kostra-python

Importere en funksjon

Funksjonene kan importeres direkte fra modulen der de ligger.

For eksempel kan funksjonen hente_data_folkemengde importeres slik:

from ssb_kostra_python.hente_data_folkemengde import hente_data_folkemengde

Funksjonen kan deretter brukes på vanlig måte:

folkemengde = hente_data_folkemengde(
    2024,
    "bydel",
    False,
)

Se tabellen over for en oversikt over hvilke moduler de forskjellige funksjonene ligger i.

Problemer med installasjon eller import

Dersom du får en feilmelding når du forsøker å importere eller bruke ssb-kostra-python, kan du gå gjennom kontrollene nedenfor.

Kort feilsøkingssjekk

Hvis pakken ikke fungerer som forventet, kan du starte med disse tre kommandoene i terminalen:

python --version
poetry show ssb-kostra-python
poetry env info

Kjør deretter dette i notebooken:

import ssb_kostra_python
import importlib.metadata

print("Pakke:", ssb_kostra_python.__file__)
print("Versjon:", importlib.metadata.version("ssb-kostra-python"))

Da får du kontrollert:

1. hvilken Python-versjon du bruker
2. hvilken versjon av ssb-kostra-python som er installert
3. hvilket Poetry-miljø som brukes
4. hvor Python faktisk finner ssb_kostra_python

Disse opplysningene vil ofte gjøre det mulig å finne årsaken dersom installasjon eller import ikke fungerer.

1. Kontroller at pakken er installert

Skriv i terminalen:

poetry show ssb-kostra-python

Hvis pakken er installert, får du blant annet opp hvilken versjon du har.

Hvis pakken ikke er installert, installer den med:

poetry add ssb-kostra-python

2. Kontroller hvilken versjon som er installert

Du kan kontrollere versjonen i terminalen:

poetry show ssb-kostra-python

Du kan også kontrollere dette fra Python:

import importlib.metadata

print(importlib.metadata.version("ssb-kostra-python"))

Dette kan være nyttig dersom en funksjon som finnes i en nyere versjon av pakken, ikke finnes i miljøet ditt.

3. Oppdater en eldre versjon

Hvis du allerede har pakken installert, kan du forsøke å oppdatere den med:

poetry update ssb-kostra-python

Kontroller deretter versjonen på nytt:

poetry show ssb-kostra-python

Hvis Poetry svarer:

No dependencies to install or update

selv om det finnes en nyere versjon av ssb-kostra-python, kan versjonskravet i prosjektets pyproject.toml hindre Poetry i å installere den nye versjonen.

Kontroller hvilken versjon av ssb-kostra-python som er angitt i pyproject.toml. Du kan sammenligne denne med den nyeste tilgjengelige versjonen på PyPI. Øverst på PyPI-siden vil du se versjonsnummeret ved siden av pakketittelen ssb-kostra-python, for eksempel 0.1.0.

Hvis du da for eksempel ønsker å gå over til versjon 0.1.0, kan du eksplisitt be Poetry om dette:

poetry add ssb-kostra-python@^0.1.0

4. Kontroller Python-versjonen

ssb-kostra-python krever Python 3.12 eller nyere.

Kontroller versjonen med:

python --version

Hvis du bruker en eldre Python-versjon, må Python-miljøet oppdateres før den nyeste versjonen av ssb-kostra-python kan installeres.

5. Poetry sier at Python-versjonene ikke er kompatible

Det kan hende at du bruker Python 3.12 eller nyere, men likevel får en feilmelding fra Poetry om Python-versjonen.

Da bør du kontrollere Python-kravet i prosjektets pyproject.toml.

Hvis det for eksempel står:

python = ">=3.11,<4.0"

betyr dette at prosjektet også skal kunne kjøres med Python 3.11. ssb-kostra-python krever imidlertid Python 3.12 eller nyere.

Dersom prosjektet ditt ikke trenger å støtte Python 3.11, må Python-kravet i pyproject.toml oppdateres til å kreve minst Python 3.12.

Det kan for eksempel se slik ut:

python = ">=3.12,<4.0"

Er du usikker på om Python-kravet for prosjektet kan endres, bør du avklare dette før du gjør endringen.

Forsøk deretter å installere eller oppdatere pakken på nytt.

6. Kontroller hvilket Python-miljø som brukes

Det er mulig å ha flere Python-miljøer samtidig. Da kan pakken være installert i ett miljø, mens notebooken din bruker et annet.

Du kan se hvor ssb_kostra_python hentes fra ved å kjøre:

import ssb_kostra_python

print(ssb_kostra_python.__file__)

Resultatet vil for eksempel kunne se slik ut:

/.../.venv/lib/python3.13/site-packages/ssb_kostra_python/__init__.py

Du kan også undersøke Poetry-miljøet fra terminalen:

poetry env info

Hvis miljøene ikke stemmer overens, må du sørge for at notebooken bruker Python-miljøet der pakken er installert.

7. Restart kernel etter installasjon eller oppdatering

Hvis du bruker JupyterLab og nettopp har installert eller oppdatert pakken, kan det være nødvendig å restarte kernelen før den nye versjonen blir tilgjengelig.

Velg:

Kernel → Restart Kernel

og kjør deretter importen på nytt.

Bruk

På ssb-kostra-python/examples/ finner du eksempel-notebooks som gjennomgår bruken av de ulike funksjonene. Please see the Reference Guide for details.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, SSB Kostra Python is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project was generated from Statistics Norway's SSB PyPI Template.