Python - PyDDB

Bemærk til eksterne brugere - Mange af linkene i det følgende afsnit henviser til interne applikationer. Tal venligst til dit projektteam for support.

Pakken pyddb giver en klar måde for ikke-udviklere at interagere med DDB ved at forenkle syntaks og implementere bekvemmelighedsfunktioner.

Denne vejledning dækker installation og hurtig start af pakken samt en fuld reference til pakken og dens funktioner.

Funktioner

Udover at forenkle grænsefladen til interaktion med DDB API -endepunkterne, giver biblioteket andre nyttige funktioner:

Godkendelse

Klienten vil tilskynde brugeren til deres Arup -legitimationsoplysninger, når klienten er instantieret og automatisk opdaterer tokenet efter behov.

Forenklet API og implementering

Biblioteket er bygget til begyndere python brugere, der ønsker at oprette automatiserede arbejdsgange.

Vi har forenklet alle Microservice -endepunkter til et enkelt bibliotek med en konsekvent grænseflade. Dette betyder, at der er mindre at lære, og det er let at komme i gang.

Du kan opbevare kørende scripts, og vi håndterer at kontrollere for duplikater og udføre eventuelle opdateringer til dig. Typisk kan manuskripter bruges på andre projekter bare ved at ændre projektnummeret.

Udforsk let DDB -taksonomi

DDB har sin egen taksonomi: Du kan ikke bare oprette en ny type aktiv eller parameter.

Dette bibliotek giver måder at søge gennem vores eksisterende taksonomi efter navn eller UUID.

Fuldt testet

Dette bibliotek testes fuldt ud mod nuværende og fremtidige versioner af DDB API, så du kan komme i gang med selvtillid.

Pagination

Som standard returnerer vores slutpunkter den første side med data. Dette bibliotek håndterer pagination og henter alle data for dig.

IDE -support

Biblioteket er fuldt indtastet, så du kan få autocomplete og typekontrol i din IDE.

Installation og opsætning

1. Kræver Python 3.10+ (App Store) - krævet for at køre pakken.
2. Kræver Git (Service Desk) - krævet for at installere pakken.
3. Kræver GitHub -konto med Arup -e -mail - krævet for at installere pakken.
4. Anbefalet Visual Studio Code (App Store) - Anbefalet miljø til skrivning af kode.

Når du har installeret ovenstående, skal du åbne Visual Studio Code og åbne en mappe, du gerne vil gemme dit arbejde i.

Åbn en Bash-terminal og kør følgende kommandoer:

Opret et virtuelt miljø

python -m venv .venv

Aktivér det virtuelle miljø

source .venv/Scripts/activate

Installer DDB Python SDKS

pip install keyring artifacts-keyring python-dateutil
pip install ddb-user-service \
ddb-reference-data-service \
ddb-qa-service \
ddb-parameter-service \
ddb-parameter-metadata-service \
ddb-environment-context-service \
ddb-comments-service \
-i https://ovearup.pkgs.visualstudio.com/_packaging/ddb/pypi/simple/

Installer pakken PyDDB

pip install git+https://github.com/arup-group/PyDDB.git

Hurtig start

Få data

At få data fra DDB er så simpelt som at kalde den passende metode på projektobjektet. Dette vil håndtere pagination og returnerobjekter med metadata. Se på API -reference for mere information.

Importer de dele af det bibliotek, du har brug for:

from pyddb import DDB, env, Project, ParameterType

Instant klienten og indstil miljøet:

ddb = DDB(env.sandbox)

Få et eksisterende DDB -projekt:

my_project = Project.get_by_number(project_number="21515700")

Få data fra projektet:

project_parameters = my_project.get_parameters()
project_assets = my_project.get_assets()
project_sources = my_project.get_sources()

Få data fra taksonomien:

all_parameter_types = ParameterType.get_all()
some_parameter_types = ParameterType.search('area')
my_parameter_type = ParameterType.get("Plot area")

Indsendelse af data

Importer de dele af det bibliotek, du har brug for:

from pyddb import DDB, env, Project, ParameterType, AssetType, Unit, Source, Parameter, Asset

Instant klienten og indstil miljøet:

ddb = DDB(env.sandbox)

Opret et projekt eller få et eksisterende:

project = Project.put("21515700")

Definer de aktiver, du vil sende:

assets = [
    my_site := Asset.create(
        asset_type=AssetType.get("site"),
        name="My DDB Site",
        parent=None,
    ),
    my_building := Asset.create(
        asset_type=AssetType.get("building"),
        name="My DDB Building",
        parent=my_site,
    )
]

Definer de parametre, du vil sende:

parameters = [
    Parameter.create(
        parameter_type=ParameterType.get("Plot area"),
        value=240,
        unit=Unit.get("m²"),
        parent=my_site,
        source=Source.create(
            source_type = SourceType.get("Derived Value"),
            title="My source title",
            reference="My source reference",
        ),
    )
]

Send dataene:

project.post_assets(assets)
project.post_parameters(parameters)

Hver af disse postmetoder returnerer det, de lægger, og tilføjer ikke duplikatdata. Indsendelse af nye parametre tilsidesætter ikke eksisterende parametre, hvis værdien, enheden eller kilden ikke er ændret.

Dette betyder, at disse metoder kan bruges til oprettede automatiserede arbejdsgange.

API -reference

Disse dokumenter er opdelt efter klasse og giver en beskrivelse og eksempel på, hvordan de skal bruges. I dette bibliotek har vi to hovedtyper af klasser, der tjener forskellige formål:

Dataklasser Disse repræsenterer værdierne for vores data og er det, du vil sende og gentage for at interagere med dine projektdata. Disse vil typisk være bundet til taksonomiklasserne, så vi ved, hvilken slags data vi arbejder med.

Taxonomiklasser Disse klasser, såsom 'ParameterType' eller 'AssetType', bestemmes af vores team. Dette er måder at kategorisere vores data på og give dem kontekst.

Kort sagt, dataklasserne er de data, du arbejder med, og taksonomiklasserne er de måder, vi klassificerer dem på. Du kan også udforske vores ordliste For mere information om de vilkår, vi bruger.

Dataklasser

Det Ddb og Projekt Klasser er de vigtigste indgangspunkter for biblioteket. Klassen DDB bruges i hvert script til at instantiere klienten og indstille miljøet. Klassen DDB bruges til at få adgang til data på tværs af projekter, mens Project -klassen bruges til at få adgang til data på et specifikt projekt.

Ddb

DDB -klassen er hovedklassen for klienten. Det bruges til at instantiere klienten og indstille miljøet. Alle scripts skal instantiere klienten med det miljø, de arbejder i.

from pyddb import DDB, env
ddb_client = DDB(env.sandbox)

Du kan nu bruge dette til at få adgang til data på tværs af projekter. Det anbefales at bruge meget specifikke forespørgsler til at reducere mængden af returnerede data.

all_projects = ddb_client.get_projects()
all_plot_areas = ddb_client.get_parameters(
 parameter_type_id=[
 ParameterType.get("Plot area").id
 ]
)

Projekt

Projektklassen bruges til at få adgang til data på et specifikt projekt. Det er instantieret ved at overføre projektnummeret til get_by_number eller put metoder.

from pyddb import DDB, env, Project

DDB(env.sandbox)

my_project = Project.get_by_number("00000000")
my_project = Project.put("00000000")

Forskellen mellem disse to metoder er, at get_by_number kun returnerer projektet, hvis det findes i DDB. put opretter projektet, hvis det ikke findes.

Kilde

Kildeklassen bruges til at oprette og postkilder til DDB. En ny kilde instantieres ved at videregive kildetype, titel og henvisning til create -metoden.

from pyddb import DDB, env, Project, Source, SourceType

DDB(env.sandbox)

my_source = Source.create(
    title="My source title",
    reference="My source reference",
    source_type=SourceType.get("Derived Value"),
)

Kilder kan sendes til DDB ved at videregive en liste over kilder til post_sources -metoden på en Project.

my_project = Project.put("00000000")
my_project.post_sources([my_source])

Kilder på et projekt kan gengives ved at kalde get_sources -metoden på en Project.

project_sources = my_project.get_sources()

Dette betyder, at det er meget let at få kilder fra et tidligere projekt og genbruge dem i et nyt projekt.

Aktiv

Klassen Asset bruges til at oprette og placere aktiver til DDB. Et nyt aktiv instantieres ved at videregive navnet, aktivtypen og forælderen til create -metoden.

En vigtig ting at bemærke er, at du i DDB ikke kan have to aktiver med samme navn, type og forælder. Dette betyder, at et enkelt sted ikke kan have to bygninger med samme navn. Dette bibliotek bruger denne logik til at forhindre, at duplikataktiver oprettes, og i stedet returnerer de eksisterende aktiver, hvis manuskripter køres igen.

from pyddb import DDB, env, Project, Asset, AssetType

DDB(env.sandbox)

my_asset = Asset.create(
    name="My asset name",
    asset_type=AssetType.get("Site"),
)

my_other_asset = Asset.create(
    name="My other asset name",
    asset_type=AssetType.get("Building"),
    parent=my_asset,
)

yet_another_asset = Asset.create(
    asset_sub_type=AssetSubType.get("Cooling"),
    parent=my_other_asset,
)

Der er et par regler for oprettelse af aktiver:

• Aktiver har brug for enten en AssetType eller en AssetSubType, så vi ved, hvilken slags aktiv det er.
• Aktiver uden AssetSubType har brug for et navn.
• Aktiver skal følge hierarkiet af aktivtypen. For eksempel skal et Building aktiv have et Site aktiv som forælder.

Du kan udforske AssetType -klassen for at få en forståelse af hierarkiet eller bruge DDB UI.

Aktiver kan sendes til DDB ved at videregive en liste over aktiver til post_assets -metoden på en Project.

my_project = Project.put("00000000")
my_project.post_assets([my_asset, my_other_asset, yet_another_asset])

Aktiver på et projekt kan gengives ved at kalde get_assets -metoden på en Project.

project_assets = my_project.get_assets()

Dette betyder, at det er meget let at få aktiver fra et tidligere projekt og genbruge dem i et nyt projekt.

Parameter

Klassen Parameter bruges til at oprette og efter parametre til DDB. En ny parameter instantieres ved at videregive parametertypen, værdi, enhed, kilde og forælder til create -metoden.

Du ønsker at være bekendt med klasser Source og Asset, før du sender parametre.

from pyddb import DDB, env, Project, Parameter, ParameterType, Source, SourceType, Asset, AssetType

DDB(env.sandbox)

my_source = Source.create(
    title="My source title",
    reference="My source reference",
    source_type=SourceType.get("Derived Value"),
)

my_site = Asset.create(
    name="My site name",
    asset_type=AssetType.get("Site"),
)

my_parameter = Parameter.create(
    parameter_type=ParameterType.get("Height"),
    value=100,
    unit="m",
    source=my_source,
    parent=my_site,
)

Parametre kan placeres til DDB ved at videregive en liste over parametre til post_parameters -metoden på en Project.

my_project = Project.put("00000000")
my_project.post_parameters([my_parameter])

En Parameter kan oprettes med kun en ParameterType, som når den sendes, vil skabe en tom parameter uden værdier. Når du er placeret med en værdi, kontrollerer biblioteket, om værdien, enheden eller kilden har ændret og opdateret parameteren, hvis det har gjort det.

Vi kan også sende kommentarer sammen med vores parametre med værdier.

parameter_with_comment = Parameter.create(
    parameter_type=ParameterType.get("Location"),
    value="Glasgow, Scotland",
    source=my_source,
    comment="Includes the city of Glasgow and the surrounding area.",
)

Taxonomiklasser

Disse klasser repræsenterer de forskellige måder, vi har klassificeret vores data på.

Som et eksempel har vi tusinder af Parameter dataklasser i vores projekter, og disse er alle klassificeret af et par ParameterType taksonomiklasse. Dette kan være hundreder af Parameter objekter med ParameterType af "område".

Disse klasser bruges til at give kontekst til dataene, give dem konsekvent struktur og gøre det lettere at arbejde med.

Alle disse klasser har 3 almindelige metoder, som du vil bruge til at interagere med dem:

get_all - Dette vil returnere alle taksonomiobjekter af den type i DDB.

search - Dette returnerer en liste over taksonomiobjekter, der matcher søgeudtrykket.

get - Dette returnerer et enkelt taksonomi -objekt ved navn eller UUID.

Kildetype

DDB har en taksonomi for kildetyper. Eksempler på disse inkluderer 'antagelse', 'afledt værdi' og 'industriens vejledning'.

from pyddb import DDB, env, SourceType

DDB(env.sandbox)

all_source_types = SourceType.get_all()
my_source_type = SourceType.get("Derived Value")
my_source_type.id
my_source_type.name

Aktivtype

DDB har en taksonomi for aktivtyper. Eksempler på disse inkluderer 'site', 'bygning', 'rum', 'bro', 'tunnel' og 'vej'.

from pyddb import DDB, env, AssetType

DDB(env.sandbox)

all_asset_types = AssetType.get_all()
my_asset_type = AssetType.get("Site")
my_asset_type.id
my_asset_type.name

Nogle aktivtyper har undertyper. Du kan kontrollere deres asset_sub_type boolske egenskab for at se, om de har undertyper.

if my_asset_type.asset_sub_type:
    sub_types = my_asset_type.get_sub_types()

Asset Subtype

DDB -taksonomien understøtter yderligere klassificering af aktivtyper til undertyper. Når en aktivtype har undertyper, skal alle forekomster af den type klassificeres som en af undertyperne.

Som et eksempel har 'bygningssystemet' AssetType flere undertyper, herunder 'opvarmning', 'afkøling' og 'belysning'. Alle aktiver af denne type skal være en af disse undertyper.

from pyddb import DDB, env, AssetSubType

DDB(env.sandbox)

all_asset_sub_types = AssetSubType.get_all()
my_asset_sub_type = AssetSubType.get("Heating")
my_asset_sub_type.id
my_asset_sub_type.name
my_asset_sub_type.asset_type_id

Parametertype

DDB har en taksonomi for parametertyper. Eksempler på disse inkluderer 'sommer indendørs tør pære temperatur', 'elasticitetsmodul', 'dato for sidste inspektion'.

Disse bruges til at klassificere vores Parameters og anvende nogle regler på dem, såsom de enheder, de kan have, eller de datatyper, de kan være.

from pyddb import DDB, env, ParameterType

DDB(env.sandbox)

all_parameter_types = ParameterType.get_all()
my_parameter_type = ParameterType.get("Modulus of elasticity")

my_parameter_type.id
my_parameter_type.name
my_parameter_type.data_type
my_parameter_type.unit_type

Varetype

En ItemType er en kombination af en AssetType, en ParameterType og potentielt en AssetSubType.

Disse er skabt af vores team og gør forskellige ParameterTypes tilgængelige på forskellige Assets baseret på deres AssetType og AssetSubType. Vi kan bruge ItemType -klassen til at se, hvilke ParameterTypes der er tilgængelige til forskellige AssetTypes.

from pyddb import DDB, env, ItemType

DDB(env.sandbox)

all_item_types = ItemType.get_all()

site_item_types = ItemType.get_by_asset_type(AssetType.get("Site"))

ItemTypes Tillad os at anvende endnu mere specifikke regler på vores data, såsom en liste over tilgængelige Options. For eksempel kan der være en ItemType, der repræsenterer felttypen ParameterType 'på AssetType' -stedet '. Denne ItemType kunne have en liste over Options, der repræsenterer de forskellige typer felter, der kan vælges, såsom 'Brownfield' eller 'Greenfield'. Dette ville betyde, at i DDB ville alle værdier af 'felttype' på 'site' aktiver være nødt til at være en af disse to muligheder.

for item_type in site_item_types:
    if item_type.has_options:
        options = item_type.get_options()

Mulighed

En Option er en værdi, der kan vælges til en Parameter af en bestemt ItemType. Dette er forudindstillede lister over værdier, der er tilladt for forskellige ItemTypes.

Du kan få adgang til deres værdier gennem egenskaben 'værdi':

for option in options:
    print(option.value)

Enhedstype

DDB har en taksonomi for enhedstyper. Eksempler på disse inkluderer 'temperatur', 'længde', 'område' og 'volumen'.

Disse giver os mulighed for at gruppere enheder, der er ens, såsom 'Celsius' og 'Fahrenheit', begge er i enhedstypen 'temperatur'. ParameterTypes har en unit_type egenskab, der bruges til at begrænse de enheder, der kan bruges til den ParameterType.

from pyddb import DDB, env, UnitType

DDB(env.sandbox)

all_unit_types = UnitType.get_all()
my_unit_type = UnitType.get("Temperature")
my_unit_type.id
my_unit_type.name```

Du kan også hente alle enheder til en given `UnitType`.

```python
my_unit_type = UnitType.get('Length')
length_units = my_unit_unit.get_units()

Enhedssystem

DDB har en taksonomi for enhedssystemer. Eksempler på disse inkluderer 'si', 'imperial' og 'generelt'.

Disse giver os mulighed for yderligere at klassificere vores enheder.

from pyddb import DDB, env, UnitSystem

DDB(env.sandbox)

all_unit_systems = UnitSystem.get_all()
my_unit_system = UnitSystem.get("General")
my_unit_system.id
my_unit_system.name

Du kan også hente alle enheder til en given UnitSystem.

my_unit_system = UnitSystem.get('General')
general_units = my_unit_unit.get_units()

Enhed

DDB har en taksonomi for enheder. Eksempler på disse inkluderer 'm', 'kg' og 'ft'.

from pyddb import DDB, env, Unit

DDB(env.sandbox)
all_units = Unit.get_all()
my_unit = Unit.get("m")
my_unit.id
my_unit.symbol

Rolletype

Rolletyper definerer forskellige typer adgang til DDB -projektet. En enkelt bruger kan have flere roller.

De forskellige rolletyper er:

Admin - Til ændring af brugertilladelser

Reader - Til læsning af projektdata

Editor - Til redigering af projektdata

Checker - Til opdatering af QA -status

Approver - Til godkendelse af data

RoleType er et Enum objekt.

from pyddb import DDB, env, Project, RoleType
DDB(env.sandbox)

project = Project.put('00000000')

project.put_user_roles([
    (RoleType.Admin, '[email protected]'),
    (RoleType.Editor, '[email protected]'),
])

Tag

Tags bruges til at organisere vores data og kan være nyttige til filtrering og søgning. Eksempler på disse inkluderer 'Google', 'Skotland' og 'mekanisk'.

from pyddb import DDB, env, Tag, Project, Asset, Parameter

DDB(env.sandbox)

all_tags = Tag.get_all()
my_tag = Tag.get("Google")

project = Project.put('00000000')
some_asset = project.get_assets()[0]
some_parameter = some_asset.get_parameters()[0]

project.post_tags([my_tag])
some_asset.post_tags([my_tag])
some_parameter.post_tags([my_tag])

TAG TYPE

Tags er grupperet sammen af deres TagTypes. Eksempler på disse inkluderer 'klient', 'region' og 'arbejdsstation'.

from pyddb import DDB, env, TagType

DDB(env.sandbox)

all_tag_types = TagType.get_all()
my_tag_type = TagType.get("Client")

client_tags = my_tag_type.get_tags()