[](https://pypi.org/project/woningwaardering/)
[](https://github.com/astral-sh/ruff)
# Woningwaardering
> ⚠️ Deze release kan gebruikt worden voor zelfstandige woonruimten volgens het beleidsboek van januari 2024. Toegestane peildatum is daarom vanaf 1 januari 2024 tot 1 juli 2024. De implementatie van het beleidsboek van juli 2024 (Wet Betaalbare Huur) voor zelfstandige en onzelfstandige woonruimten wordt momenteel ontwikkeld en later dit jaar gereleased.
📊 **Status**
Het Microservices team van Woonstad Rotterdam is in Q1 2024 begonnen met het ontwikkelen met een open-source Python-package waarmee het mogelijk wordt om het puntensysteem van het [woningwaarderingsstelsel](https://aedes.nl/huurbeleid-en-betaalbaarheid/woningwaarderingsstelsel-wws) toe te passen. We gaan hierbij uit van de [VERA-standaard](https://www.coraveraonline.nl/index.php/VERA-standaard) van de corporatiesector voor de in- en output van de package. Dit project heeft drie hoofddoelen:
- dat het mogelijk is om de woningwaardering te berekenen op basis van een digitale representatie van woning:
- steeds meer woningcorperaties en bedrijven digitaliseren hun woningbestand, bijvoorbeeld met behulp van een bouwwerkinformatiemodel (BIM).
- de combinatie van digitale representaties van woningen en deze package maakt het mogelijk om de woningwaardering in bulk te berekenen.
- door deze package als API te gebruiken kan de woningwaardering in een webapplicatie worden geïntegreerd.
- om tot een completere woningwaarderingsstelsel-berekening te komen dan die nu beschikbaar zijn via tools zoals bijvoorbeeld die van de [huurcommissie](https://www.huurcommissie.nl/huurders/sociale-huurwoning/maximale-huurprijs-berekenen).
- om als woningcorporatie of bedrijf te blijven voldoen aan de wetging zoals [Wet Betaalbare Huur](https://www.volkshuisvestingnederland.nl/onderwerpen/wet-betaalbare-huur).
---
_Voorbeeld van hoe wij de woningwaardering package gebruiken bij Woonstad Rotterdam_.
---
Momenteel wordt er gewerkt aan de implementatie van de woningwaardering van zelfstandige woonruimten volgens het gepubliceerde beleidsboek van de huurcommissie in juli 2024.
Het beleidsboek van januari 2024 voor zelfstandige woonruimten is afgerond voor zover deze geïmplementeerd kon worden en zal vanaf nu niet meer worden uitgebreid.
Voor meer details over wat er precies is geïmplementeerd van het beleidsboek van januari 2024 verwijzen wij naar de [documentatie](https://github.com/woonstadrotterdam/woningwaardering/blob/v1.0.1/docs/implementatietoelichting-beleidsboeken/zelfstandige_woonruimten.md) over de implementatie van dit beleidsboek.
Voor meer informatie over hoe documentatie van het beleidsboek is gemaakt, verwijzen wij naar het hoofdstuk [Implementatie beleidsboek huurcommissie](https://github.com/woonstadrotterdam/woningwaardering/tree/v1.0.1?tab=readme-ov-file#implementatie-beleidsboek-huurcommissie) in deze `README`.
Voor vragen kunt u contact opnemen met Product Owner en mede-developer van Team Microservices [Tomer Gabay](mailto:tomer.gabay@woonstadrotterdam.nl) of één van de andere maintainers van deze repo.
## Inhoudsopgave
- [Woningwaardering](#woningwaardering)
- [Inhoudsopgave](#inhoudsopgave)
- [1. Opzet woningwaardering-package](#1-opzet-woningwaardering-package)
- [Implementatie beleidsboek huurcommissie](#implementatie-beleidsboek-huurcommissie)
- [Repository-structuur](#repository-structuur)
- [Design](#design)
- [Lookup tabellen](#lookup-tabellen)
- [2. Contributing](#2-contributing)
- [Setup](#setup)
- [Naamgeving van classes](#naamgeving-van-classes)
- [Stelsels](#stelsels)
- [Stelselgroepen](#stelselgroepen)
- [Testing](#testing)
- [Conventies voor tests](#conventies-voor-tests)
- [Test modellen](#test-modellen)
- [Datamodellen](#datamodellen)
- [Datamodellen uitbreiden](#datamodellen-uitbreiden)
- [Referentiedata](#referentiedata)
- [3. Datamodel uitbreidingen](#3-datamodel-uitbreidingen)
- [Ruimtedetailsoort kast](#ruimtedetailsoort-kast)
- [Verbonden ruimten](#verbonden-ruimten)
- [Gedeeld met aantal eenheden](#gedeeld-met-aantal-eenheden)
- [Bouwkundige elementen](#bouwkundige-elementen)
## 1. Opzet woningwaardering-package
### Implementatie beleidsboek huurcommissie
Voor het berekenen van een woningwaardering worden de [beleidsboeken van de Nederlandse Huurcommissie](https://www.huurcommissie.nl/huurcommissie-helpt/beleidsboeken) voor de waarderingstelsels voor zelfstandige en onzelfstandige woningen gevolgd.
De beleidsboeken van de Huurcommissie Nederland volgen Nederlandse wet- en regelgeving zoals beschreven in [Artikel 14 van het "Besluit huurprijzen woonruimte"](https://wetten.overheid.nl/BWBR0003237/2024-01-01#Artikel14).
Om berekeningen te maken met betrekking tot een woningwaardering wordt het gepubliceerde beleid vertaald naar Python-code.
Een woningwaardering wordt gemaakt op basis van woningelementen.
De stelselgroepen waarop gescoord wordt, zijn vastgelegd in het [woningwaarderingstelselgroep](https://www.coraveraonline.nl/index.php/Referentiedata:WONINGWAARDERINGSTELSELGROEP) op www.coraveraonline.nl.
Deze worden aangehouden in de opzet van de `woningwaardering`-package.
Voor elke stelselgroep wordt een apart Python-object gemaakt met een naam die overeenkomt met [woningwaarderingstelselgroep](https://www.coraveraonline.nl/index.php/Referentiedata:WONINGWAARDERINGSTELSELGROEP).
De woningwaardering package volgt de [beleidsboeken van de Nederlandse Huurcommissie](https://www.huurcommissie.nl/huurcommissie-helpt/beleidsboeken) en daarmee de Nederlandse wet en regelgeving m.b.t. het waarderen van woningen. Tijdens de ontwikkeling van deze package komt het voor dat we inconsistenties in de beleidsboeken vinden of dat er ruimte is voor interpretatie. Daarnaast kan het voorkomen dat dat de VERA modellen, met eventuele uitbreidingen, niet toereikend zijn om de stelselgroep voglens het beleidsboek tot op de letter nauwkeurig te implementeren. In [implementatietoelichting-beleidsboeken](docs/implementatietoelichting-beleidsboeken) onderbouwen wij hoe elke stelselgroep is geïmplementeerd en welke keuzes daarin gemaakt zijn.
In deze documenten wordt bijgehouden welke onderdelen van het beleidsboek wel en niet zijn geïmplementeerd per stelselgroep. De gepubliceerde tekst uit het beleidsboek wordt gekopieerd en wanneer een onderdeel niet in de code van de package is geïmplementeerd zal dit worden aangegeven met ~~doorgestreepte tekst~~.
De reden van het niet implementeren van een regelonderdeel is vrijwel altijd dat het technisch niet mogelijk is op basis van het inputmodel van de VERA-standaard. Een voorbeeld hiervan is dat voor oppervlakte van vertrekken in 2024 de minimale breedte van een vertrek over de volledige lengte 1,5m moet zijn. Omdat wij de data van de minimale breedte over de volledige lengte niet binnenkrijgen via het inputmodel kunnen wij dit onderdeel van de regel niet implementeren. **Dit betekent dat het aan de gebruiker is om met deze regelonderdelen rekening te houden bij het eenheid-inputmodel.** Een deel van de deze regelonderdelen wordt al afgevangen indien het eenheid-inputmodel voldoet aan de NEN-norm.
Regels die wel zijn geimplementeerd zijn niet doorgestreept.
Keuzes die zijn gemaakt en of interpretaties die zijn gedaan, worden in een gemarkeerd blok weergegeven zoals hieronder is gedaan.
> Dit is een tekstblok waarmee commentaar van een developer wordt aangegeven in het beleidsboek.
### Repository-structuur
De repository-structuur is ingedeeld volgens de [referentiedata van stelselgroepen van de VERA-standaard](https://www.coraveraonline.nl/index.php/Referentiedata:WONINGWAARDERINGSTELSELGROEP); eerst de stelsels (bijvoorbeeld _zelfstandig_, _onzelfstandig_) en vervolgens de stelselgroepen (bijvoorbeeld _Energieprestatie_, _Wasgelegenheid_).
In de folders van de stelselgroepen bevindt zich de code voor het berekenen van de punten per stelselgroep.
### Design
Het design van de `woningwaardering`-package is zo gekozen dat stelselgroep-objecten en bijbehorende regels modulair zijn.
### Lookup tabellen
In lookup tabellen worden constanten en variabelen opgeslagen die nodig zijn bij het berekenen van de punten voor een stelselgroep.
In de `woningwaardering` package wordt CSV gebruikt als bestandstype voor het opslaan van een lookup tabel.
De keuze is op CSV gevallen omdat lookup data soms bestaat uit meerdere datarijen waardoor dit vaak minder leesbaar wordt wanneer dit bijvoorbeeld in json of yaml wordt opgeslagen.
### Warnings
In de `woningwaardering` package worden `UserWarnings` gegenereerd wanneer de inputdata niet volledig of correct wordt aangeleverd.
Deze waarschuwingen worden gegeven met een warning bericht en een type warning, bijvoorbeeld:
```python
warnings.warn("Dit is een warning", UserWarning)
```
Standaard genereert de `woningwaardering` package een error wanneer een `UserWarning` wordt gegeven.
Hoewel de package kan werken met incomplete data, is ervoor gekozen om standaard te falen bij incomplete inputdata, zodat de gebruiker hiervan op de hoogte wordt gebracht.
Het is echter ook mogelijk om het warning filter terug te zetten naar de standaardinstellingen, waardoor een warning m.b.t. incomplete data niet leidt tot een error, maar slechts een _warning_:
```python
warnings.simplefilter("default", UserWarning)
```
Alle waarschuwingen die worden gegenereerd met `warnings.warn()`, worden standaard gelogd met `logger.warning()` en weergegeven in het standaardfout bestand.
Mocht door de gebruiker logging worden uitgezet, dan zullen de UserWarnings altijd te zien zijn voor de gebruiker in de output van de _stderr_.
#### Warning vs Exception
Er wordt doorgaans in de stelgroepversies gebruik gemaakt van `warnings.warn()` in plaats van het raisen van een exception.
Hierdoor bestaat de mogelijkheid om stelselgroepen te berekenen voor stelselgroepen waarvoor de data wel compleet genoeg is, mits de `warnings.simplefilter` naar `default` is gezet.
## 2. Contributing
### Setup
Om de woningwaardering-package en de daarbij behorende developer dependencies te installeren, run onderstaand command:
```
git clone https://github.com/woonstadrotterdam/woningwaardering.git
cd woningwaardering
pip install -e ".[dev]"
```
### Naamgeving van classes
Voor de naamgeving van de classes in de woningwaardering module volgen we de VERA referentiedata. Deze referentiedata is gedefinieerd in de referentiedata enums, te vinden onder [woningwaardering/vera/referentiedata](woningwaardering/vera/referentiedata).
#### Genereren opzet woningwaarderingstelsels en -groepen
Om alle onderstaande naamgevingen correct en consequent door te voeren, is er een task beschikbaar die de opzet van een woningwaarderingstelsel en -groep volgens deze regels voor je kan aanmaken.
Zorg er voor dat [Task](https://taskfile.dev/installation/) en de dev dependencies zijn geïnstalleerd:
```
pip install -e ".[dev]"
```
Vervolgens voer je onderstaand command uit:
```
task genereer-opzet-woningwaarderinggroep
```
Dit script stelt je een aantal vragen, waarna de code voor het stelsel en de stelselgroep aangemaakt worden.
#### Stelsels
De namen voor de stelsels zijn te vinden in de `Woningwaarderingstelsel` Enum. Bijvoorbeeld: het stelsel voor zelfstandige woonruimten wordt aangeduid als `Woningwaarderingstelsel.zelfstandige_woonruimten`. De implementatie van dit `Stelsel` bevindt zich in [woningwaardering/stelsels/zelfstandige_woonruimten/zelfstandige_woonruimten.py](woningwaardering/stelsels/zelfstandige_woonruimten/zelfstandige_woonruimten.py).
De geldigheid van een stelsel wordt bepaald door de begin- en einddatum, die in de constructor van de corresponderende klasse worden vastgelegd.
#### Stelselgroepen
De namen voor de stelselgroepen zijn te vinden in de `Woningwaarderingstelselgroep` Enum. Bijvoorbeeld: de stelselgroep voor oppervlakte van vertrekken wordt aangeduid als `Woningwaarderingstelselgroep.oppervlakte_van_vertrekken`. De implementatie van deze `Stelselgroep` bevindt zich in [woningwaardering/stelsels/zelfstandige_woonruimten/oppervlakte_van_vertrekken/oppervlakte_van_vertrekken.py](woningwaardering/stelsels/zelfstandige_woonruimten/oppervlakte_van_vertrekken/oppervlakte_van_vertrekken.py).
De geldigheid van een stelselgroep wordt bepaald door de begin- en einddatum, die in de constructor van de corresponderende klasse worden vastgelegd.
### Releasemanagement
#### Versienummering
Voor versienummering maken we gebruik van [SemVer](https://semver.org/lang/nl/):
Bij SemVer wordt een versienummer in de vorm MAJOR.MINOR.PATCH gebruikt, waarbij elk element als volgt wordt verhoogd:
- `MAJOR` wordt verhoogd bij incompatibele API-wijzigingen,
- `MINOR` wordt verhoogd bij het toevoegen van functionaliteit die compatibel is met de vorige versie, en
- `PATCH` wordt verhoogd bij compatibele bugfixes.
Er zijn aanvullende labels beschikbaar voor pre-release en build-metadata om toe te voegen aan het `MAJOR.MINOR.PATCH`-formaat.
Bijvoorbeeld: stel dat de huidige versie `0.1.3-alpha` is.
- De suffix `-alpha` wordt gebruikt zolang de software nog niet volledig is, bijvoorbeeld zolang nog niet alle beoogde stelselgroepen geïmplementeerd zijn
- Wanneer een nieuwe release alleen compatibele bugfixes of updates van dependencies bevat, wordt de nieuwe versie `0.1.4-alpha`
- Wanneer een nieuwe release ook compatibele nieuwe functionaliteit toevoegt, bijvoorbeeld de implementatie van een nieuwe stelselgroep, dan wordt de nieuwe versie `0.2.0-alpha`.
- Wanneer alle beoogde stelselgroepen geïmplementeerd zijn, wordt de nieuwe versie `1.0.0-beta`. De publieke api mag vanaf dan enkel nog backwards-compatible wijzigen.
- Wanneer de software volledig is en in productie genomen wordt, wordt de nieuwe versie `1.0.0`
- Wanneer er een incompatible wijziging is in de VERA modellen, wordt de nieuwe versie `2.0.0`, eventueel met het `-alpha` of `-beta` label, afhankelijk van de implementatiestatus.
#### Releaseproces
Om een nieuwe release te starten, moet er een Git tag aangemaak worden volgens het format `v<versienummer>`. De prefix `v` geeft aan dat de tag een versiepunt markeert.
Bijvoorbeeld:
```cli
$ git tag v0.2.3-alpha
$ git push --tags
```
Hiermee start het releaseproces, gedefinieerd in een GitHub workflow: [.github/workflows/publish-to-pypi.ymls](.github/workflows/publish-to-pypi.yml)
In dit proces wordt een package aangemaakt met een [Python versienummer](https://packaging.python.org/en/latest/discussions/versioning/), afgeleid van het SemVer nummer in de tag. Bijvoorbeeld: `0.2.3-alpha` wordt `0.2.3a0`
De package wordt eerst gepubliceerd op [TestPyPi](https://test.pypi.org/project/woningwaardering/). Na goedkeuring wordt de package naar [PyPi](https://pypi.org/project/woningwaardering/) gepubliceerd. Daarna wordt er een release aangemaakt in GitHub, met een changelog met de titel en link naar alle pull requests die deel uitmaken van deze release.
### Testing
Voor het testen van code wordt het [pytest framework](https://docs.pytest.org/en/8.0.x/index.html) gebruikt. Meer informatie is te vinden over het framework.
Passende tests worden altijd met de nieuw geschreven code opgeleverd.
Er zijn verschillende "test-scopes" te bedenken, zoals het testen van details en specifieke functies.
Daarnaast is het testen van een hele keten of stelselgroep-object ook vereist.
Bij het opleveren van nieuwe code moet aan beide test-scopes gedacht worden.
#### Test coverage rapport
Na het uitvoeren van `pytest` wordt er een code coverage report getoond. Hierin is per file te zien welk percentage van de code in de files getest is.
Daarnaast wordt de code coverage ook naar een file `lcov.info` geschreven. Die kan gebruikt worden in VSCode om de coverage weer te geven met een plugin zoals "Coverage Gutters".
#### Conventies voor tests
Tests worden toegevoegd aan de `tests`-folder in de root van de repository.
Voor de structuur in de `tests`-folder wordt dezelfde structuur aangehouden als die in de `woningwaardering`-folder.
De naam van het bestand waarin de tests staan geschreven is `test_<file_name>.py`.
Elke testfunctie begint met `test_`, gevolgd door de naam van de functie of class die getest wordt, bijvoorbeeld `def test_<functie_naam>()` of `def test_<ClassNaam>()`.
Hierin wordt de naam de van de functie of class exact gevolgd.
Voor pytest is `test_` een indicator om de functie te herkennen als een testfunctie.
Stel dat de functionaliteiten van `woningwaardering/stelsels/zelfstandige_woonruimten/oppervlakte_van_vertrekken/oppervlakte_van_vertrekken.py` getest moeten worden, dan is het pad naar het bijbehorende testbestand `tests/stelsels/zelfstandige_woonruimten/oppervlakte_van_vertrekken/test_oppervlakte_van_vertrekken.py`.
In `test_oppervlakte_van_vertrekken.py` worden testfuncties geschreven met bijbehorende naamconventies.
Hieronder is de functienaamconventie en python code weergegeven voor het testen van een losse functie (`def losse_functie`):
```python
def test_losse_functie() -> None:
assert losse_functie() == True
```
Als er een class getest wordt, bijvoorbeeld `OppervlakteVanVertrekken`, dan is de testfunctie opzet als volgt:
```python
def test_OppervlakteVanVertrekken():
opp_v_v = OppervlakteVanVertrekken()
assert self.opp_v_v.functie_een() == 1
assert self.opp_v_v.functie_twee() == 2
```
#### Test modellen
Om de woningwaardering-package zo nauwkeurig mogelijk te testen, zijn er eenheidmodellen (in .json format) toegevoegd in `tests/data/...`. De modellen volgen de VERA standaard en dienen als een testinput voor de geschreven tests. Omdat er gewerkt wordt met peildata en de berekening van een stelselgroep per jaar kan veranderen worden de outputmodellen per jaar opgeslagen. Zie bijvoorbeeld de folder `tests/data/zelfstandige_woonruimten/output/peildatum/2024-01-01`. Deze bevat de output voor de inputmodellen met als peildatum 2024-01-01 of later. Op deze manier kunnen dezelfde inputmodellen in tests met verschillende peildata getest worden. De resulterende outputs zijn met de hand nagerekend om de kwaliteit van de tests te garanderen.
Om heel specifieke regelgeving uit het beleidsboek te testen, kunnen er handmatig test modellen gemaakt worden. Deze test modellen worden opgeslagen in de test folder van een stelselgroep waarvoor de specifieke regelgeving die getest wordt. Zie bijvoorbeeld `tests/data/zelfstandige_woonruimten/stelselgroepen/oppervlakte_van_vertrekken/input/gedeelde_berging.json`: hier is een gedeelde berging gedefinieerd om een specifieke set van regels in oppervlakte_van_vertrekken te testen.
### Logger Guidelines
In de woningwaardering package wordt de logger van `loguru` gebruikt voor logging.
Voor het developen in de woningwaardering package worden de logging levels `DEBUG`, `INFO`, `WARNING` en `ERROR` gebruikt.
De verschillende levels worden gebruikt voor de verschillende types van logging, zoals beschreven in de [python 3.11 documentatie](https://docs.python.org/3.11/library/logging.html#logging-levels).
Hieronder is de tabel van de python documentatie gekopieerd waarin de verschillende logging levels staan beschreven.
De tabel is aangevuld met de kolom "Gebruik Woningwaardering Package", waarin wordt aangegeven met voorbeelden welke soort logging gedaan wordt op de verschillende logging levels.
| Level | Numerieke waarde | Wat het betekent / Wanneer te gebruiken | Gebruik Woningwaardering Package |
| -------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NOTSET | 0 | Wanneer ingesteld op een logger, geeft dit aan dat bovenliggende loggers geraadpleegd moeten worden om het effectieve niveau te bepalen. Als dit nog steeds NOTSET oplevert, worden alle gebeurtenissen gelogd. Wanneer ingesteld op een handler, worden alle gebeurtenissen afgehandeld. | Wordt niet gebruikt in de woningwaardering package. |
| DEBUG | 10 | Gedetailleerde informatie, meestal alleen van belang voor een ontwikkelaar die een probleem probeert te diagnosticeren. | Wordt alleen gebruikt om details weer the geven aan een developer. bijvoorbeeld: wat een functie terug geeft of welke type een variabele heeft. |
| INFO | 20 | Bevestiging dat alles werkt zoals verwacht. | Bevat beschrijvingen van de werking van de code. Bijvoorbeeld: Het berekende resultaat voor een stelselgroep of welke code op basis van de input data wordt gerund. |
| WARNING | 30 | Een indicatie dat er iets onverwachts is gebeurd, of dat er in de nabije toekomst een probleem kan optreden (bijv. 'schijfruimte bijna vol'). De software werkt nog steeds zoals verwacht. | Een warning wordt gelogd wanneer er bijvoorbeeld iets mist in de input data of een functie deprecated is. Dit kan er toe leiden dat bepaalde code niet uitgevoerd kan worden. Voor warnings aan de package gebruiker, wordt altijd `warnings.warn()` gebruikt. Zie het kopje [warnings](#warnings) voor meer informatie over het geven van warnings voor gebruikers en hoe hier mee omgegaan wordt. |
| ERROR | 40 | Vanwege een ernstiger probleem heeft de software een bepaalde functie niet kunnen uitvoeren. | Een error wordt in de woningwaardering package gelogd wanneer het gedrag verwacht is en de error een extra toelichting nodig heeft. Wanneer een error kritiek is voor het functioneren van de package wordt deze error geraisd. Ook kan het voorkomen dat de verwachte error toegestaan is. Dit kan bijvoorbeeld in een `try`/`except` patroon. Er kan dan gekozen worden om de error te loggen maar niet te raisen. Hierdoor kan het programma wel doorgaan en is het wel duidelijk dat er een `exception` heeft plaatsgevonden. Zoals een error geraisd kan worden en het programma kan laten stoppen, zo kunnen warnings ook geraisd worden om het progromma te stoppen. |
| CRITICAL | 50 | Een ernstige fout, die aangeeft dat het programma zelf mogelijk niet meer kan blijven draaien. | Wordt niet gebruikt in de woningwaardering package. |
### Datamodellen
De datamodellen in de `woningwaardering` package zijn gebaseerd op de OpenAPI-specificatie van het [VERA BVG domein](https://aedes-datastandaarden.github.io/vera-openapi/Ketenprocessen/BVG.html).
Wanneer je deze modellen wilt bijwerken, zorg er dan voor dat [Task](https://taskfile.dev/installation/) en de dev dependencies zijn geïnstalleerd:
```
pip install -e ".[dev]"
```
Vervolgens kan je met dit commando de modellen in deze repository bijwerken:
```
task genereer-vera-bvg-modellen
```
De classes voor deze modellen worden gegeneerd in `woningwaardering/vera/bvg/generated.py`
#### Datamodellen uitbreiden
Wanneer de VERA modellen niet toereikend zijn om de woningwaardering te berekenen, kan het VERA model uitgebreid worden.
Maak hiervoor altijd eerst een issue aan in de [VERA OpenApi repository](https://github.com/Aedes-datastandaarden/vera-openapi).
Maak vervolgens in de map [woningwaardering/vera/bvg/model_uitbreidingen](woningwaardering/vera/bvg/model_uitbreidingen) een class aan met de missende attributen. De naamgeving voor deze classes is: `_{classNaam}`.
Zet in de class bij het toegevoegde attribuut een comment met een link naar het issue in de VERA OpenApi repository zodat duidelijk is waar de toevoeging voor dient, en we kunnen volgen of de aanpassing is doorgevoerd in de VERA modellen.
Daarnaast neem je in de class een docstring op met uitleg over het gebruik en doel van de uitbreiding.
Bijvoorbeeld: voor het uitbreiden van de class `EenhedenRuimte` maak je een class `_EenhedenRuimte` aan:
```python
from typing import Optional
from pydantic import BaseModel, Field
class _EenhedenRuimte(BaseModel):
# https://github.com/Aedes-datastandaarden/vera-openapi/issues/44
gedeeld_met_aantal_eenheden: Optional[int] = Field(
default=None, alias="gedeeldMetAantalEenheden"
)
"""
Het aantal eenheden waarmee deze ruimte wordt gedeeld. Deze waarde wordt gebruikt bij het berekenen van de waardering van een gedeelde ruimte met ruimtedetailsoort berging.
"""
```
De task `genereer-vera-bvg-modellen` zal de body van deze classes samenvoegen met de gelijknamige VERA class en zo de toegevoegde attributen beschikbaar maken.
### Referentiedata
We maken gebruik van de [VERA Referentiedata](https://github.com/Aedes-datastandaarden/vera-referentiedata).
Wanneer je de referentiedata wilt bijwerken, zorg er dan voor dat [Task](https://taskfile.dev/installation/) is geïnstalleerd
Vervolgens kan je met dit commando de referentiedata in deze repository bijwerken:
```
task genereer-vera-referentiedata
```
De referentiedata wordt gegenereerd in `woningwaardering/vera/referentiedata`
## 3. Datamodel uitbreidingen
Tijdens de ontwikkeling van de woningwaardering-package komt het voor dat de VERA modellen niet toereikend zijn om de punten voor een stelselgroep te berekenen. Daarom kunnen er indien nodig uitbreidingen gemaakt worden op de VERA modellen. In deze sectie onderbouwen en documenteren wij deze uitbreidingen. In de sectie Referentiedata wordt uitgelegd hoe [uitbreidingen toe te voegen](#datamodellen-uitbreiden) als contributor van dit project.
### Ruimtedetailsoort kast
Binnen het woningwaarderingsstelsel mag onder bepaalde voorwaarden de oppervlakte van vaste kasten worden opgeteld bij de ruimte waar de deur van de kast zich bevindt. Als hier bij het inmeten geen rekening mee gehouden is, kan het attribuut verbonden_ruimten gebruikt worden om de met een ruimte verbonden vaste kasten mee te laten nemen in de waardering. Hiervoor is de VERA referentiedata binnen deze repository uitgebreid met ruimtedetailsoort `Kast`, code `KAS`.
### Verbonden ruimten
Het attribuut `verbonden_ruimten` bevat de ruimten die in verbinding staan met de ruimte die het attribuut bezit. `verbonden_ruimten` wordt gebruikt bij het berekenen van de waardering van kasten en verwarming van ruimten. `verbonden_ruimten` heeft type `Optional[list[EenhedenRuimte]]` en is een uitbreiding op `EenhedenRuimte`. Voor deze uitbreiding staat een [github issue](https://github.com/Aedes-datastandaarden/vera-openapi/issues/47) open ter aanvulling op het VERA model.
### Gedeeld met aantal eenheden
Het attribuut `gedeeld_met_aantal_eenheden` geeft het aantal eenheden weer waarmee een bepaalde ruimte wordt gedeeld. Dit attribuut wordt gebruikt bij het berekenen van de waardering van een gedeelde ruimte met ruimtedetailsoort berging. `gedeeld_met_aantal_eenheden` heeft als type `Optional[int]`. Er staat een github issue open voor deze aanvulling op het VERA model: https://github.com/Aedes-datastandaarden/vera-openapi/issues/44
### Bouwkundige elementen
In de beleidsboeken wordt soms op basis van een bouwkundig element dat aanwezig is in een ruimte, een uitzondering of nuance op een regel besproken. Dit kan bijvoorbeeld tot gevolg hebben dat er punten in mindering worden gebracht, of punten extra gegeven worden. Bijvoorbeeld bij de berekening van de oppervlakte van een zolder als vertrek of als overige ruimte is er informatie nodig over de trap waarmee de zolder te bereiken is. Daartoe is het VERA model `EenhedenRuimte` uitgebreid met het attribuut `bouwkundige_elementen` met als type `Optional[list[BouwkundigElementenBouwkundigElement]]`. Er staat een github issue open om `bouwkundige_elementen` standaard in het VERA model toe te voegen: https://github.com/Aedes-datastandaarden/vera-openapi/issues/46
### Verwarmd
In de VERA standaard is nog geen mogelijkheid om aan te geven of een ruimte verwarmd is. Het attribuut `verwarmde_vertrekken_aantal` bestaat wel, maar dit bestaat op niveau van de eenheid en daarin bestaat geen onderscheid tussen vertrekken en overige ruimten. Dit is aangekaart in deze twee issues:
- https://github.com/Aedes-datastandaarden/vera-openapi/issues/41
- https://github.com/Aedes-datastandaarden/vera-referentiedata/issues/100
Raw data
{
"_id": null,
"home_page": null,
"name": "woningwaardering",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "woning, waardering, stelsel, woningwaarderingsstelsel, wws",
"author": null,
"author_email": "Woonstad Rotterdam <info@woonstadrotterdam.nl>, Ben Verhees <ben.verhees@woonstadrotterdam.nl>, Tiddo Loos <tiddo.loos@woonstadrotterdam.nl>, Tomer Gabay <tomer.gabay@woonstadrotterdam.nl>",
"download_url": "https://files.pythonhosted.org/packages/40/70/87ea409f61026071890f9d8b292384191522fc1c153864c2adb49e34bbb0/woningwaardering-1.0.2.tar.gz",
"platform": null,
"description": "\n\n[](https://pypi.org/project/woningwaardering/)\n\n[](https://github.com/astral-sh/ruff)\n\n# Woningwaardering\n\n> \u26a0\ufe0f Deze release kan gebruikt worden voor zelfstandige woonruimten volgens het beleidsboek van januari 2024. Toegestane peildatum is daarom vanaf 1 januari 2024 tot 1 juli 2024. De implementatie van het beleidsboek van juli 2024 (Wet Betaalbare Huur) voor zelfstandige en onzelfstandige woonruimten wordt momenteel ontwikkeld en later dit jaar gereleased.\n\n\ud83d\udcca **Status**\n\n \n \n\n\nHet Microservices team van Woonstad Rotterdam is in Q1 2024 begonnen met het ontwikkelen met een open-source Python-package waarmee het mogelijk wordt om het puntensysteem van het [woningwaarderingsstelsel](https://aedes.nl/huurbeleid-en-betaalbaarheid/woningwaarderingsstelsel-wws) toe te passen. We gaan hierbij uit van de [VERA-standaard](https://www.coraveraonline.nl/index.php/VERA-standaard) van de corporatiesector voor de in- en output van de package. Dit project heeft drie hoofddoelen:\n\n- dat het mogelijk is om de woningwaardering te berekenen op basis van een digitale representatie van woning:\n - steeds meer woningcorperaties en bedrijven digitaliseren hun woningbestand, bijvoorbeeld met behulp van een bouwwerkinformatiemodel (BIM).\n - de combinatie van digitale representaties van woningen en deze package maakt het mogelijk om de woningwaardering in bulk te berekenen.\n - door deze package als API te gebruiken kan de woningwaardering in een webapplicatie worden ge\u00efntegreerd.\n- om tot een completere woningwaarderingsstelsel-berekening te komen dan die nu beschikbaar zijn via tools zoals bijvoorbeeld die van de [huurcommissie](https://www.huurcommissie.nl/huurders/sociale-huurwoning/maximale-huurprijs-berekenen).\n- om als woningcorporatie of bedrijf te blijven voldoen aan de wetging zoals [Wet Betaalbare Huur](https://www.volkshuisvestingnederland.nl/onderwerpen/wet-betaalbare-huur).\n\n---\n\n\n_Voorbeeld van hoe wij de woningwaardering package gebruiken bij Woonstad Rotterdam_.\n\n---\n\nMomenteel wordt er gewerkt aan de implementatie van de woningwaardering van zelfstandige woonruimten volgens het gepubliceerde beleidsboek van de huurcommissie in juli 2024.\nHet beleidsboek van januari 2024 voor zelfstandige woonruimten is afgerond voor zover deze ge\u00efmplementeerd kon worden en zal vanaf nu niet meer worden uitgebreid.\nVoor meer details over wat er precies is ge\u00efmplementeerd van het beleidsboek van januari 2024 verwijzen wij naar de [documentatie](https://github.com/woonstadrotterdam/woningwaardering/blob/v1.0.1/docs/implementatietoelichting-beleidsboeken/zelfstandige_woonruimten.md) over de implementatie van dit beleidsboek.\nVoor meer informatie over hoe documentatie van het beleidsboek is gemaakt, verwijzen wij naar het hoofdstuk [Implementatie beleidsboek huurcommissie](https://github.com/woonstadrotterdam/woningwaardering/tree/v1.0.1?tab=readme-ov-file#implementatie-beleidsboek-huurcommissie) in deze `README`.\n\nVoor vragen kunt u contact opnemen met Product Owner en mede-developer van Team Microservices [Tomer Gabay](mailto:tomer.gabay@woonstadrotterdam.nl) of \u00e9\u00e9n van de andere maintainers van deze repo.\n\n## Inhoudsopgave\n\n- [Woningwaardering](#woningwaardering)\n - [Inhoudsopgave](#inhoudsopgave)\n - [1. Opzet woningwaardering-package](#1-opzet-woningwaardering-package)\n - [Implementatie beleidsboek huurcommissie](#implementatie-beleidsboek-huurcommissie)\n - [Repository-structuur](#repository-structuur)\n - [Design](#design)\n - [Lookup tabellen](#lookup-tabellen)\n - [2. Contributing](#2-contributing)\n - [Setup](#setup)\n - [Naamgeving van classes](#naamgeving-van-classes)\n - [Stelsels](#stelsels)\n - [Stelselgroepen](#stelselgroepen)\n - [Testing](#testing)\n - [Conventies voor tests](#conventies-voor-tests)\n - [Test modellen](#test-modellen)\n - [Datamodellen](#datamodellen)\n - [Datamodellen uitbreiden](#datamodellen-uitbreiden)\n - [Referentiedata](#referentiedata)\n - [3. Datamodel uitbreidingen](#3-datamodel-uitbreidingen)\n - [Ruimtedetailsoort kast](#ruimtedetailsoort-kast)\n - [Verbonden ruimten](#verbonden-ruimten)\n - [Gedeeld met aantal eenheden](#gedeeld-met-aantal-eenheden)\n - [Bouwkundige elementen](#bouwkundige-elementen)\n\n## 1. Opzet woningwaardering-package\n\n### Implementatie beleidsboek huurcommissie\n\nVoor het berekenen van een woningwaardering worden de [beleidsboeken van de Nederlandse Huurcommissie](https://www.huurcommissie.nl/huurcommissie-helpt/beleidsboeken) voor de waarderingstelsels voor zelfstandige en onzelfstandige woningen gevolgd.\nDe beleidsboeken van de Huurcommissie Nederland volgen Nederlandse wet- en regelgeving zoals beschreven in [Artikel 14 van het \"Besluit huurprijzen woonruimte\"](https://wetten.overheid.nl/BWBR0003237/2024-01-01#Artikel14).\n\nOm berekeningen te maken met betrekking tot een woningwaardering wordt het gepubliceerde beleid vertaald naar Python-code.\nEen woningwaardering wordt gemaakt op basis van woningelementen.\nDe stelselgroepen waarop gescoord wordt, zijn vastgelegd in het [woningwaarderingstelselgroep](https://www.coraveraonline.nl/index.php/Referentiedata:WONINGWAARDERINGSTELSELGROEP) op www.coraveraonline.nl.\nDeze worden aangehouden in de opzet van de `woningwaardering`-package.\nVoor elke stelselgroep wordt een apart Python-object gemaakt met een naam die overeenkomt met [woningwaarderingstelselgroep](https://www.coraveraonline.nl/index.php/Referentiedata:WONINGWAARDERINGSTELSELGROEP).\n\nDe woningwaardering package volgt de [beleidsboeken van de Nederlandse Huurcommissie](https://www.huurcommissie.nl/huurcommissie-helpt/beleidsboeken) en daarmee de Nederlandse wet en regelgeving m.b.t. het waarderen van woningen. Tijdens de ontwikkeling van deze package komt het voor dat we inconsistenties in de beleidsboeken vinden of dat er ruimte is voor interpretatie. Daarnaast kan het voorkomen dat dat de VERA modellen, met eventuele uitbreidingen, niet toereikend zijn om de stelselgroep voglens het beleidsboek tot op de letter nauwkeurig te implementeren. In [implementatietoelichting-beleidsboeken](docs/implementatietoelichting-beleidsboeken) onderbouwen wij hoe elke stelselgroep is ge\u00efmplementeerd en welke keuzes daarin gemaakt zijn.\nIn deze documenten wordt bijgehouden welke onderdelen van het beleidsboek wel en niet zijn ge\u00efmplementeerd per stelselgroep. De gepubliceerde tekst uit het beleidsboek wordt gekopieerd en wanneer een onderdeel niet in de code van de package is ge\u00efmplementeerd zal dit worden aangegeven met ~~doorgestreepte tekst~~. \nDe reden van het niet implementeren van een regelonderdeel is vrijwel altijd dat het technisch niet mogelijk is op basis van het inputmodel van de VERA-standaard. Een voorbeeld hiervan is dat voor oppervlakte van vertrekken in 2024 de minimale breedte van een vertrek over de volledige lengte 1,5m moet zijn. Omdat wij de data van de minimale breedte over de volledige lengte niet binnenkrijgen via het inputmodel kunnen wij dit onderdeel van de regel niet implementeren. **Dit betekent dat het aan de gebruiker is om met deze regelonderdelen rekening te houden bij het eenheid-inputmodel.** Een deel van de deze regelonderdelen wordt al afgevangen indien het eenheid-inputmodel voldoet aan de NEN-norm.\nRegels die wel zijn geimplementeerd zijn niet doorgestreept.\nKeuzes die zijn gemaakt en of interpretaties die zijn gedaan, worden in een gemarkeerd blok weergegeven zoals hieronder is gedaan.\n\n> Dit is een tekstblok waarmee commentaar van een developer wordt aangegeven in het beleidsboek.\n\n### Repository-structuur\n\nDe repository-structuur is ingedeeld volgens de [referentiedata van stelselgroepen van de VERA-standaard](https://www.coraveraonline.nl/index.php/Referentiedata:WONINGWAARDERINGSTELSELGROEP); eerst de stelsels (bijvoorbeeld _zelfstandig_, _onzelfstandig_) en vervolgens de stelselgroepen (bijvoorbeeld _Energieprestatie_, _Wasgelegenheid_).\nIn de folders van de stelselgroepen bevindt zich de code voor het berekenen van de punten per stelselgroep.\n\n### Design\n\nHet design van de `woningwaardering`-package is zo gekozen dat stelselgroep-objecten en bijbehorende regels modulair zijn.\n\n### Lookup tabellen\n\nIn lookup tabellen worden constanten en variabelen opgeslagen die nodig zijn bij het berekenen van de punten voor een stelselgroep.\nIn de `woningwaardering` package wordt CSV gebruikt als bestandstype voor het opslaan van een lookup tabel.\nDe keuze is op CSV gevallen omdat lookup data soms bestaat uit meerdere datarijen waardoor dit vaak minder leesbaar wordt wanneer dit bijvoorbeeld in json of yaml wordt opgeslagen.\n\n### Warnings\n\nIn de `woningwaardering` package worden `UserWarnings` gegenereerd wanneer de inputdata niet volledig of correct wordt aangeleverd.\nDeze waarschuwingen worden gegeven met een warning bericht en een type warning, bijvoorbeeld:\n\n```python\nwarnings.warn(\"Dit is een warning\", UserWarning)\n```\n\nStandaard genereert de `woningwaardering` package een error wanneer een `UserWarning` wordt gegeven.\nHoewel de package kan werken met incomplete data, is ervoor gekozen om standaard te falen bij incomplete inputdata, zodat de gebruiker hiervan op de hoogte wordt gebracht.\nHet is echter ook mogelijk om het warning filter terug te zetten naar de standaardinstellingen, waardoor een warning m.b.t. incomplete data niet leidt tot een error, maar slechts een _warning_:\n\n```python\nwarnings.simplefilter(\"default\", UserWarning)\n```\n\nAlle waarschuwingen die worden gegenereerd met `warnings.warn()`, worden standaard gelogd met `logger.warning()` en weergegeven in het standaardfout bestand.\nMocht door de gebruiker logging worden uitgezet, dan zullen de UserWarnings altijd te zien zijn voor de gebruiker in de output van de _stderr_.\n\n#### Warning vs Exception\n\nEr wordt doorgaans in de stelgroepversies gebruik gemaakt van `warnings.warn()` in plaats van het raisen van een exception.\nHierdoor bestaat de mogelijkheid om stelselgroepen te berekenen voor stelselgroepen waarvoor de data wel compleet genoeg is, mits de `warnings.simplefilter` naar `default` is gezet.\n\n## 2. Contributing\n\n### Setup\n\nOm de woningwaardering-package en de daarbij behorende developer dependencies te installeren, run onderstaand command:\n\n```\ngit clone https://github.com/woonstadrotterdam/woningwaardering.git\ncd woningwaardering\npip install -e \".[dev]\"\n```\n\n### Naamgeving van classes\n\nVoor de naamgeving van de classes in de woningwaardering module volgen we de VERA referentiedata. Deze referentiedata is gedefinieerd in de referentiedata enums, te vinden onder [woningwaardering/vera/referentiedata](woningwaardering/vera/referentiedata).\n\n#### Genereren opzet woningwaarderingstelsels en -groepen\n\nOm alle onderstaande naamgevingen correct en consequent door te voeren, is er een task beschikbaar die de opzet van een woningwaarderingstelsel en -groep volgens deze regels voor je kan aanmaken.\n\nZorg er voor dat [Task](https://taskfile.dev/installation/) en de dev dependencies zijn ge\u00efnstalleerd:\n\n```\npip install -e \".[dev]\"\n```\n\nVervolgens voer je onderstaand command uit:\n\n```\ntask genereer-opzet-woningwaarderinggroep\n```\n\nDit script stelt je een aantal vragen, waarna de code voor het stelsel en de stelselgroep aangemaakt worden.\n\n#### Stelsels\n\nDe namen voor de stelsels zijn te vinden in de `Woningwaarderingstelsel` Enum. Bijvoorbeeld: het stelsel voor zelfstandige woonruimten wordt aangeduid als `Woningwaarderingstelsel.zelfstandige_woonruimten`. De implementatie van dit `Stelsel` bevindt zich in [woningwaardering/stelsels/zelfstandige_woonruimten/zelfstandige_woonruimten.py](woningwaardering/stelsels/zelfstandige_woonruimten/zelfstandige_woonruimten.py).\nDe geldigheid van een stelsel wordt bepaald door de begin- en einddatum, die in de constructor van de corresponderende klasse worden vastgelegd.\n\n#### Stelselgroepen\n\nDe namen voor de stelselgroepen zijn te vinden in de `Woningwaarderingstelselgroep` Enum. Bijvoorbeeld: de stelselgroep voor oppervlakte van vertrekken wordt aangeduid als `Woningwaarderingstelselgroep.oppervlakte_van_vertrekken`. De implementatie van deze `Stelselgroep` bevindt zich in [woningwaardering/stelsels/zelfstandige_woonruimten/oppervlakte_van_vertrekken/oppervlakte_van_vertrekken.py](woningwaardering/stelsels/zelfstandige_woonruimten/oppervlakte_van_vertrekken/oppervlakte_van_vertrekken.py).\nDe geldigheid van een stelselgroep wordt bepaald door de begin- en einddatum, die in de constructor van de corresponderende klasse worden vastgelegd.\n\n### Releasemanagement\n\n#### Versienummering\n\nVoor versienummering maken we gebruik van [SemVer](https://semver.org/lang/nl/):\n\nBij SemVer wordt een versienummer in de vorm MAJOR.MINOR.PATCH gebruikt, waarbij elk element als volgt wordt verhoogd:\n\n- `MAJOR` wordt verhoogd bij incompatibele API-wijzigingen,\n- `MINOR` wordt verhoogd bij het toevoegen van functionaliteit die compatibel is met de vorige versie, en\n- `PATCH` wordt verhoogd bij compatibele bugfixes.\n\nEr zijn aanvullende labels beschikbaar voor pre-release en build-metadata om toe te voegen aan het `MAJOR.MINOR.PATCH`-formaat.\n\nBijvoorbeeld: stel dat de huidige versie `0.1.3-alpha` is.\n\n- De suffix `-alpha` wordt gebruikt zolang de software nog niet volledig is, bijvoorbeeld zolang nog niet alle beoogde stelselgroepen ge\u00efmplementeerd zijn\n- Wanneer een nieuwe release alleen compatibele bugfixes of updates van dependencies bevat, wordt de nieuwe versie `0.1.4-alpha`\n- Wanneer een nieuwe release ook compatibele nieuwe functionaliteit toevoegt, bijvoorbeeld de implementatie van een nieuwe stelselgroep, dan wordt de nieuwe versie `0.2.0-alpha`.\n- Wanneer alle beoogde stelselgroepen ge\u00efmplementeerd zijn, wordt de nieuwe versie `1.0.0-beta`. De publieke api mag vanaf dan enkel nog backwards-compatible wijzigen.\n- Wanneer de software volledig is en in productie genomen wordt, wordt de nieuwe versie `1.0.0`\n- Wanneer er een incompatible wijziging is in de VERA modellen, wordt de nieuwe versie `2.0.0`, eventueel met het `-alpha` of `-beta` label, afhankelijk van de implementatiestatus.\n\n#### Releaseproces\n\nOm een nieuwe release te starten, moet er een Git tag aangemaak worden volgens het format `v<versienummer>`. De prefix `v` geeft aan dat de tag een versiepunt markeert.\n\nBijvoorbeeld:\n\n```cli\n$ git tag v0.2.3-alpha\n$ git push --tags\n```\n\nHiermee start het releaseproces, gedefinieerd in een GitHub workflow: [.github/workflows/publish-to-pypi.ymls](.github/workflows/publish-to-pypi.yml)\n\nIn dit proces wordt een package aangemaakt met een [Python versienummer](https://packaging.python.org/en/latest/discussions/versioning/), afgeleid van het SemVer nummer in de tag. Bijvoorbeeld: `0.2.3-alpha` wordt `0.2.3a0`\n\nDe package wordt eerst gepubliceerd op [TestPyPi](https://test.pypi.org/project/woningwaardering/). Na goedkeuring wordt de package naar [PyPi](https://pypi.org/project/woningwaardering/) gepubliceerd. Daarna wordt er een release aangemaakt in GitHub, met een changelog met de titel en link naar alle pull requests die deel uitmaken van deze release.\n\n### Testing\n\nVoor het testen van code wordt het [pytest framework](https://docs.pytest.org/en/8.0.x/index.html) gebruikt. Meer informatie is te vinden over het framework.\nPassende tests worden altijd met de nieuw geschreven code opgeleverd.\nEr zijn verschillende \"test-scopes\" te bedenken, zoals het testen van details en specifieke functies.\nDaarnaast is het testen van een hele keten of stelselgroep-object ook vereist.\nBij het opleveren van nieuwe code moet aan beide test-scopes gedacht worden.\n\n#### Test coverage rapport\n\nNa het uitvoeren van `pytest` wordt er een code coverage report getoond. Hierin is per file te zien welk percentage van de code in de files getest is.\nDaarnaast wordt de code coverage ook naar een file `lcov.info` geschreven. Die kan gebruikt worden in VSCode om de coverage weer te geven met een plugin zoals \"Coverage Gutters\".\n\n#### Conventies voor tests\n\nTests worden toegevoegd aan de `tests`-folder in de root van de repository.\nVoor de structuur in de `tests`-folder wordt dezelfde structuur aangehouden als die in de `woningwaardering`-folder.\nDe naam van het bestand waarin de tests staan geschreven is `test_<file_name>.py`.\nElke testfunctie begint met `test_`, gevolgd door de naam van de functie of class die getest wordt, bijvoorbeeld `def test_<functie_naam>()` of `def test_<ClassNaam>()`.\nHierin wordt de naam de van de functie of class exact gevolgd.\nVoor pytest is `test_` een indicator om de functie te herkennen als een testfunctie.\n\nStel dat de functionaliteiten van `woningwaardering/stelsels/zelfstandige_woonruimten/oppervlakte_van_vertrekken/oppervlakte_van_vertrekken.py` getest moeten worden, dan is het pad naar het bijbehorende testbestand `tests/stelsels/zelfstandige_woonruimten/oppervlakte_van_vertrekken/test_oppervlakte_van_vertrekken.py`.\nIn `test_oppervlakte_van_vertrekken.py` worden testfuncties geschreven met bijbehorende naamconventies.\nHieronder is de functienaamconventie en python code weergegeven voor het testen van een losse functie (`def losse_functie`):\n\n```python\ndef test_losse_functie() -> None:\n assert losse_functie() == True\n```\n\nAls er een class getest wordt, bijvoorbeeld `OppervlakteVanVertrekken`, dan is de testfunctie opzet als volgt:\n\n```python\n\ndef test_OppervlakteVanVertrekken():\n opp_v_v = OppervlakteVanVertrekken()\n assert self.opp_v_v.functie_een() == 1\n assert self.opp_v_v.functie_twee() == 2\n```\n\n#### Test modellen\n\nOm de woningwaardering-package zo nauwkeurig mogelijk te testen, zijn er eenheidmodellen (in .json format) toegevoegd in `tests/data/...`. De modellen volgen de VERA standaard en dienen als een testinput voor de geschreven tests. Omdat er gewerkt wordt met peildata en de berekening van een stelselgroep per jaar kan veranderen worden de outputmodellen per jaar opgeslagen. Zie bijvoorbeeld de folder `tests/data/zelfstandige_woonruimten/output/peildatum/2024-01-01`. Deze bevat de output voor de inputmodellen met als peildatum 2024-01-01 of later. Op deze manier kunnen dezelfde inputmodellen in tests met verschillende peildata getest worden. De resulterende outputs zijn met de hand nagerekend om de kwaliteit van de tests te garanderen.\n\nOm heel specifieke regelgeving uit het beleidsboek te testen, kunnen er handmatig test modellen gemaakt worden. Deze test modellen worden opgeslagen in de test folder van een stelselgroep waarvoor de specifieke regelgeving die getest wordt. Zie bijvoorbeeld `tests/data/zelfstandige_woonruimten/stelselgroepen/oppervlakte_van_vertrekken/input/gedeelde_berging.json`: hier is een gedeelde berging gedefinieerd om een specifieke set van regels in oppervlakte_van_vertrekken te testen.\n\n### Logger Guidelines\n\nIn de woningwaardering package wordt de logger van `loguru` gebruikt voor logging.\nVoor het developen in de woningwaardering package worden de logging levels `DEBUG`, `INFO`, `WARNING` en `ERROR` gebruikt.\nDe verschillende levels worden gebruikt voor de verschillende types van logging, zoals beschreven in de [python 3.11 documentatie](https://docs.python.org/3.11/library/logging.html#logging-levels).\nHieronder is de tabel van de python documentatie gekopieerd waarin de verschillende logging levels staan beschreven.\nDe tabel is aangevuld met de kolom \"Gebruik Woningwaardering Package\", waarin wordt aangegeven met voorbeelden welke soort logging gedaan wordt op de verschillende logging levels.\n\n| Level | Numerieke waarde | Wat het betekent / Wanneer te gebruiken | Gebruik Woningwaardering Package |\n| -------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| NOTSET | 0 | Wanneer ingesteld op een logger, geeft dit aan dat bovenliggende loggers geraadpleegd moeten worden om het effectieve niveau te bepalen. Als dit nog steeds NOTSET oplevert, worden alle gebeurtenissen gelogd. Wanneer ingesteld op een handler, worden alle gebeurtenissen afgehandeld. | Wordt niet gebruikt in de woningwaardering package. |\n| DEBUG | 10 | Gedetailleerde informatie, meestal alleen van belang voor een ontwikkelaar die een probleem probeert te diagnosticeren. | Wordt alleen gebruikt om details weer the geven aan een developer. bijvoorbeeld: wat een functie terug geeft of welke type een variabele heeft. |\n| INFO | 20 | Bevestiging dat alles werkt zoals verwacht. | Bevat beschrijvingen van de werking van de code. Bijvoorbeeld: Het berekende resultaat voor een stelselgroep of welke code op basis van de input data wordt gerund. |\n| WARNING | 30 | Een indicatie dat er iets onverwachts is gebeurd, of dat er in de nabije toekomst een probleem kan optreden (bijv. 'schijfruimte bijna vol'). De software werkt nog steeds zoals verwacht. | Een warning wordt gelogd wanneer er bijvoorbeeld iets mist in de input data of een functie deprecated is. Dit kan er toe leiden dat bepaalde code niet uitgevoerd kan worden. Voor warnings aan de package gebruiker, wordt altijd `warnings.warn()` gebruikt. Zie het kopje [warnings](#warnings) voor meer informatie over het geven van warnings voor gebruikers en hoe hier mee omgegaan wordt. |\n| ERROR | 40 | Vanwege een ernstiger probleem heeft de software een bepaalde functie niet kunnen uitvoeren. | Een error wordt in de woningwaardering package gelogd wanneer het gedrag verwacht is en de error een extra toelichting nodig heeft. Wanneer een error kritiek is voor het functioneren van de package wordt deze error geraisd. Ook kan het voorkomen dat de verwachte error toegestaan is. Dit kan bijvoorbeeld in een `try`/`except` patroon. Er kan dan gekozen worden om de error te loggen maar niet te raisen. Hierdoor kan het programma wel doorgaan en is het wel duidelijk dat er een `exception` heeft plaatsgevonden. Zoals een error geraisd kan worden en het programma kan laten stoppen, zo kunnen warnings ook geraisd worden om het progromma te stoppen. |\n| CRITICAL | 50 | Een ernstige fout, die aangeeft dat het programma zelf mogelijk niet meer kan blijven draaien. | Wordt niet gebruikt in de woningwaardering package. |\n\n### Datamodellen\n\nDe datamodellen in de `woningwaardering` package zijn gebaseerd op de OpenAPI-specificatie van het [VERA BVG domein](https://aedes-datastandaarden.github.io/vera-openapi/Ketenprocessen/BVG.html).\n\nWanneer je deze modellen wilt bijwerken, zorg er dan voor dat [Task](https://taskfile.dev/installation/) en de dev dependencies zijn ge\u00efnstalleerd:\n\n```\npip install -e \".[dev]\"\n```\n\nVervolgens kan je met dit commando de modellen in deze repository bijwerken:\n\n```\ntask genereer-vera-bvg-modellen\n```\n\nDe classes voor deze modellen worden gegeneerd in `woningwaardering/vera/bvg/generated.py`\n\n#### Datamodellen uitbreiden\n\nWanneer de VERA modellen niet toereikend zijn om de woningwaardering te berekenen, kan het VERA model uitgebreid worden.\n\nMaak hiervoor altijd eerst een issue aan in de [VERA OpenApi repository](https://github.com/Aedes-datastandaarden/vera-openapi).\n\nMaak vervolgens in de map [woningwaardering/vera/bvg/model_uitbreidingen](woningwaardering/vera/bvg/model_uitbreidingen) een class aan met de missende attributen. De naamgeving voor deze classes is: `_{classNaam}`.\n\nZet in de class bij het toegevoegde attribuut een comment met een link naar het issue in de VERA OpenApi repository zodat duidelijk is waar de toevoeging voor dient, en we kunnen volgen of de aanpassing is doorgevoerd in de VERA modellen.\n\nDaarnaast neem je in de class een docstring op met uitleg over het gebruik en doel van de uitbreiding.\n\nBijvoorbeeld: voor het uitbreiden van de class `EenhedenRuimte` maak je een class `_EenhedenRuimte` aan:\n\n```python\nfrom typing import Optional\n\nfrom pydantic import BaseModel, Field\n\n\nclass _EenhedenRuimte(BaseModel):\n # https://github.com/Aedes-datastandaarden/vera-openapi/issues/44\n gedeeld_met_aantal_eenheden: Optional[int] = Field(\n default=None, alias=\"gedeeldMetAantalEenheden\"\n )\n \"\"\"\n Het aantal eenheden waarmee deze ruimte wordt gedeeld. Deze waarde wordt gebruikt bij het berekenen van de waardering van een gedeelde ruimte met ruimtedetailsoort berging.\n \"\"\"\n```\n\nDe task `genereer-vera-bvg-modellen` zal de body van deze classes samenvoegen met de gelijknamige VERA class en zo de toegevoegde attributen beschikbaar maken.\n\n### Referentiedata\n\nWe maken gebruik van de [VERA Referentiedata](https://github.com/Aedes-datastandaarden/vera-referentiedata).\n\nWanneer je de referentiedata wilt bijwerken, zorg er dan voor dat [Task](https://taskfile.dev/installation/) is ge\u00efnstalleerd\n\nVervolgens kan je met dit commando de referentiedata in deze repository bijwerken:\n\n```\ntask genereer-vera-referentiedata\n```\n\nDe referentiedata wordt gegenereerd in `woningwaardering/vera/referentiedata`\n\n## 3. Datamodel uitbreidingen\n\nTijdens de ontwikkeling van de woningwaardering-package komt het voor dat de VERA modellen niet toereikend zijn om de punten voor een stelselgroep te berekenen. Daarom kunnen er indien nodig uitbreidingen gemaakt worden op de VERA modellen. In deze sectie onderbouwen en documenteren wij deze uitbreidingen. In de sectie Referentiedata wordt uitgelegd hoe [uitbreidingen toe te voegen](#datamodellen-uitbreiden) als contributor van dit project.\n\n### Ruimtedetailsoort kast\n\nBinnen het woningwaarderingsstelsel mag onder bepaalde voorwaarden de oppervlakte van vaste kasten worden opgeteld bij de ruimte waar de deur van de kast zich bevindt. Als hier bij het inmeten geen rekening mee gehouden is, kan het attribuut verbonden_ruimten gebruikt worden om de met een ruimte verbonden vaste kasten mee te laten nemen in de waardering. Hiervoor is de VERA referentiedata binnen deze repository uitgebreid met ruimtedetailsoort `Kast`, code `KAS`.\n\n### Verbonden ruimten\n\nHet attribuut `verbonden_ruimten` bevat de ruimten die in verbinding staan met de ruimte die het attribuut bezit. `verbonden_ruimten` wordt gebruikt bij het berekenen van de waardering van kasten en verwarming van ruimten. `verbonden_ruimten` heeft type `Optional[list[EenhedenRuimte]]` en is een uitbreiding op `EenhedenRuimte`. Voor deze uitbreiding staat een [github issue](https://github.com/Aedes-datastandaarden/vera-openapi/issues/47) open ter aanvulling op het VERA model.\n\n### Gedeeld met aantal eenheden\n\nHet attribuut `gedeeld_met_aantal_eenheden` geeft het aantal eenheden weer waarmee een bepaalde ruimte wordt gedeeld. Dit attribuut wordt gebruikt bij het berekenen van de waardering van een gedeelde ruimte met ruimtedetailsoort berging. `gedeeld_met_aantal_eenheden` heeft als type `Optional[int]`. Er staat een github issue open voor deze aanvulling op het VERA model: https://github.com/Aedes-datastandaarden/vera-openapi/issues/44\n\n### Bouwkundige elementen\n\nIn de beleidsboeken wordt soms op basis van een bouwkundig element dat aanwezig is in een ruimte, een uitzondering of nuance op een regel besproken. Dit kan bijvoorbeeld tot gevolg hebben dat er punten in mindering worden gebracht, of punten extra gegeven worden. Bijvoorbeeld bij de berekening van de oppervlakte van een zolder als vertrek of als overige ruimte is er informatie nodig over de trap waarmee de zolder te bereiken is. Daartoe is het VERA model `EenhedenRuimte` uitgebreid met het attribuut `bouwkundige_elementen` met als type `Optional[list[BouwkundigElementenBouwkundigElement]]`. Er staat een github issue open om `bouwkundige_elementen` standaard in het VERA model toe te voegen: https://github.com/Aedes-datastandaarden/vera-openapi/issues/46\n\n### Verwarmd\n\nIn de VERA standaard is nog geen mogelijkheid om aan te geven of een ruimte verwarmd is. Het attribuut `verwarmde_vertrekken_aantal` bestaat wel, maar dit bestaat op niveau van de eenheid en daarin bestaat geen onderscheid tussen vertrekken en overige ruimten. Dit is aangekaart in deze twee issues:\n\n- https://github.com/Aedes-datastandaarden/vera-openapi/issues/41\n- https://github.com/Aedes-datastandaarden/vera-referentiedata/issues/100\n",
"bugtrack_url": null,
"license": null,
"summary": "Berekent de punten van een woning op basis van het woningwaarderingsstelsel.",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/woonstadrotterdam/woningwaardering",
"Issues": "https://github.com/woonstadrotterdam/woningwaardering/issues"
},
"split_keywords": [
"woning",
" waardering",
" stelsel",
" woningwaarderingsstelsel",
" wws"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c73cdda304c753cba5d8b4b5704b9977a90ce44e532cfb3bf8d18dd1bf975497",
"md5": "7c21cf370831b29acfc23339e930387a",
"sha256": "bf4a0118fdee31c79b90bf8ecd6a51964b835b86ca74f0fcd41cd81f7bc94abc"
},
"downloads": -1,
"filename": "woningwaardering-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c21cf370831b29acfc23339e930387a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 267205,
"upload_time": "2024-09-05T15:02:05",
"upload_time_iso_8601": "2024-09-05T15:02:05.489372Z",
"url": "https://files.pythonhosted.org/packages/c7/3c/dda304c753cba5d8b4b5704b9977a90ce44e532cfb3bf8d18dd1bf975497/woningwaardering-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "407087ea409f61026071890f9d8b292384191522fc1c153864c2adb49e34bbb0",
"md5": "691f0418e3a0e015a8ad53e64c46ba0d",
"sha256": "1439a1d780d46e741dea81bcdebf8fb8b7291a91db21847cf9491611fd014deb"
},
"downloads": -1,
"filename": "woningwaardering-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "691f0418e3a0e015a8ad53e64c46ba0d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 695357,
"upload_time": "2024-09-05T15:02:07",
"upload_time_iso_8601": "2024-09-05T15:02:07.260485Z",
"url": "https://files.pythonhosted.org/packages/40/70/87ea409f61026071890f9d8b292384191522fc1c153864c2adb49e34bbb0/woningwaardering-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-05 15:02:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "woonstadrotterdam",
"github_project": "woningwaardering",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "woningwaardering"
}
JSON
