Python - PyDDB

Uwaga dla użytkowników zewnętrznych - Wiele linków w następnej sekcji patrz aplikacje wewnętrzne. Porozmawiaj ze swoim zespołem projektowym o wsparcie.

Pakiet pyddb stanowi jasny sposób dla osób niebędących programistami do interakcji z DDB poprzez uproszczenie składni i wdrażanie funkcji wygody.

Ten przewodnik obejmie instalację i szybki początek pakietu, a także pełne odniesienie do pakietu i jego funkcji.

Cechy

Oprócz znacznie uproszczenia interfejsu do interakcji z punktami końcowymi API DDB, biblioteka zapewnia inne przydatne funkcje:

Uwierzytelnianie

Klient zachęci użytkownika do swoich poświadczeń ARUP, gdy klient zostanie utworzony instancją i automatycznie odświeży token w razie potrzeby.

Uproszczony interfejs API i implementacja

Biblioteka jest zbudowana dla początkujących python użytkowników, którzy chcą tworzyć zautomatyzowane przepływy pracy.

Uprościliśmy wszystkie punkty końcowe mikrousług do jednej biblioteki o spójnym interfejsie. Oznacza to, że jest mniej do nauczenia się i łatwo jest zacząć.

Możesz przechowywać skrypty ponowne, a my obsługujemy sprawdzanie duplikatów i wykonywanie wszelkich aktualizacji dla Ciebie. Zazwyczaj scenariusze mogą być używane w innych projektach, zmieniając numer projektu.

Łatwo odkrywać taksonomię DDB

DDB ma własną taksonomię: nie możesz po prostu utworzyć nowego rodzaju zasobu lub parametru.

Ta biblioteka zapewnia sposoby przeszukiwania naszej istniejącej taksonomii według nazwy lub UUID.

W pełni przetestowane

Ta biblioteka jest w pełni przetestowana w stosunku do aktualnych i przyszłych wersji API DDB, dzięki czemu możesz zacząć z pewnością siebie.

Paginacja

Domyślnie nasze punkty końcowe zwrócą pierwszą stronę danych. Ta biblioteka obsługuje paginację i pobiera dla Ciebie wszystkie dane.

Wsparcie IDE

Biblioteka jest w pełni wpisana, dzięki czemu można uzyskać autocomplete i pisać sprawdzanie IDE.

Instalacja i konfiguracja

1. Wymaga Python 3.10+ (App Store) - wymagane do uruchomienia pakietu.
2. Wymaga git (biuro serwisowe) - wymagane do instalacji pakietu.
3. Wymaga konta GitHub z e -mailem ARUP - wymagane do zainstalowania pakietu.
4. Zalecany kod Visual Studio (App Store) - Zalecane środowisko do pisania kodu.

Po zainstalowaniu powyższego otwórz Visual Studio Code i otwórz folder, w którym chcesz przechowywać swoją pracę.

Otwórz terminal Bash i uruchom następujące polecenia:

Utwórz wirtualne środowisko

python -m venv .venv

Aktywuj środowisko wirtualne

source .venv/Scripts/activate

Zainstaluj SDK DDB Python

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/

Zainstaluj pakiet PyDDB

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

Szybki start

Uzyskanie danych

Uzyskanie danych z DDB jest tak proste, jak wywołanie odpowiedniej metody w obiekcie projektu. Obsługuje to Paginację i zwróci obiekty za pomocą metadanych. Spójrz na Odniesienie API po więcej informacji.

Zaimportuj części potrzebnej biblioteki:

from pyddb import DDB, env, Project, ParameterType

Utwórz klienta i ustaw środowisko:

ddb = DDB(env.sandbox)

Uzyskaj istniejący projekt DDB:

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

Uzyskaj dane z projektu:

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

Uzyskaj dane z taksonomii:

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

Publikowanie danych

Zaimportuj części potrzebnej biblioteki:

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

Utwórz klienta i ustaw środowisko:

ddb = DDB(env.sandbox)

Utwórz projekt lub zdobądź istniejący:

project = Project.put("21515700")

Zdefiniuj zasoby, które chcesz opublikować:

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,
    )
]

Zdefiniuj parametry, które chcesz opublikować:

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",
        ),
    )
]

Opublikuj dane:

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

Każda z tych metod postu zwróci to, co publikują i nie doda duplikatów danych. Publikowanie nowych parametrów nie zastąpi istniejących parametrów, jeśli wartość, jednostka lub źródło nie ulegnie zmianie.

Oznacza to, że metody te można wykorzystać do tworzenia automatycznych przepływów pracy.

Odniesienie API

Dokumenty te są rozkładane przez klasę i podają opis i przykład tego, jak należy je użyć. W tej bibliotece mamy dwa główne typy klas, które służą różnym celom:

Zajęcia danych : Reprezentują one wartości naszych danych i są tym, co będziesz publikować i wyświetlać w interakcji z danymi projektu. Zazwyczaj są one związane z klasami taksonomii, więc wiemy, z jakim rodzajem danych pracujemy.

Zajęcia taksonomii : Klasy te, takie jak „ParameterType” lub „AssetType”, są określane przez nasz zespół. Są to sposoby kategoryzacji naszych danych i podania ich kontekstu.

Krótko mówiąc, klasy danych to dane, z którymi pracujesz, a klasy taksonomii to sposób, w jaki je klasyfikujemy. Możesz także zbadać nasze słowniczek Aby uzyskać więcej informacji na temat używanych warunków.

Zajęcia danych

. DDB I Projekt Zajęcia są głównymi punktami wejścia dla biblioteki. Klasa DDB jest używana w każdym skrypcie do tworzenia instancji klienta i ustawienia środowiska. Klasa DDB służy do dostępu do danych w różnych projektach, podczas gdy klasa Project służy do dostępu do danych w określonym projekcie.

DDB

Klasa DDB jest główną klasą dla klienta. Służy do tworzenia instancji klienta i ustawienia środowiska. Wszystkie skrypty powinny ulepszyć klienta w środowisko, w którym pracują.

from pyddb import DDB, env

ddb_client = DDB(env.sandbox)

Możesz teraz użyć tego do dostępu do danych w różnych projektach. Zaleca się użycie bardzo konkretnych zapytań w celu zmniejszenia ilości zwróconych danych.

all_projects = ddb_client.get_projects()

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

Projekt

Klasa projektu służy do dostępu do danych dotyczących określonego projektu. Jest to utworzone przez przekazanie numeru projektu do metod get_by_number lub put.

from pyddb import DDB, env, Project

DDB(env.sandbox)

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

Różnica między tymi dwiema metodami polega na tym, że get_by_number zwróci projekt tylko wtedy, gdy istnieje w DDB. put utworzy projekt, jeśli nie istnieje.

Źródło

Klasa źródłowa służy do tworzenia i postu źródeł do DDB. Nowe źródło jest tworzone, przekazując typ źródła, tytuł i odniesienie do metody create.

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"),
)

Źródła można wysłać na DDB, przekazując listę źródeł do metody post_sources na Project.

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

Źródła w projekcie można odzyskać, wywołując metodę get_sources na Project.

project_sources = my_project.get_sources()

Oznacza to, że bardzo łatwo jest uzyskać źródła z poprzedniego projektu i ponownie je wykorzystać w nowym projekcie.

Zaleta

Klasa Asset służy do tworzenia i publikowania zasobów do DDB. Nowy zasób jest utworzony, przekazując nazwę, typ aktywów i rodzic do metody create.

Jedną ważną rzeczą, na którą należy zwrócić uwagę, jest to, że w DDB nie możesz mieć dwóch zasobów o tej samej nazwie, typu i rodzica. Oznacza to, że jedna strona nie może mieć dwóch budynków o tej samej nazwie. Ta biblioteka używa tej logiki, aby zapobiec tworzeniu duplikatów zasobów i zamiast tego zwróci istniejące zasoby, jeśli skrypty są powtórne.

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,
)

Istnieje kilka zasad tworzenia aktywów:

• Aktywa potrzebują AssetType lub AssetSubType, więc wiemy, jaki to jest zasób.
• Aktywa bez AssetSubType potrzebują nazwy.
• Aktywa muszą przestrzegać hierarchii typu aktywów. Na przykład zasób Building musi mieć zasób Site jako rodzic.

Możesz zbadać klasę AssetType, aby zrozumieć hierarchię lub użyć interfejsu użytkownika DDB.

Aktywa można wysłać na DDB, przekazując listę aktywów do metody post_assets w Project.

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

Aktywa w projekcie można odzyskać, wywołując metodę get_assets na Project.

project_assets = my_project.get_assets()

Oznacza to, że bardzo łatwo jest uzyskać zasoby z poprzedniego projektu i ponownie je wykorzystać w nowym projekcie.

Parametr

Klasa Parameter służy do tworzenia i publikowania parametrów do DDB. Nowy parametr jest tworzony, przekazując typ parametru, wartość, jednostkę, źródło i nadrzędne do metody create.

Będziesz chciał zapoznać się z klasami Source i Asset przed opublikowaniem parametrów.

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,
)

Parametry można zamieścić na DDB, przekazując listę parametrów do metody post_parameters na Project.

my_project = Project.put("00000000")

my_project.post_parameters([my_parameter])

Parameter można utworzyć za pomocą ParameterType, który po opublikowaniu utworzy pusty parametr bez żadnych wartości. Po opublikowaniu wartości biblioteka sprawdzi, czy wartość, jednostka lub źródło zmieniła się i zaktualizuje parametr, jeśli tak.

Możemy również publikować komentarze wraz z naszymi parametrami o wartościach.

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.",
)

Zajęcia taksonomii

Klasy te reprezentują różne sposoby, w jakie sklasyfikowaliśmy nasze dane.

Jako przykład mamy tysiące klas danych Parameter w naszych projektach, a wszystkie są sklasyfikowane przez kilka klas taksonomii ParameterType. Może to być setki obiektów Parameter z ParameterType „obszaru”.

Klasy te są wykorzystywane do dostarczania kontekstu danych, nadania mu spójnej struktury i ułatwienia pracy.

Wszystkie te klasy mają 3 wspólne metody, których użyjesz do interakcji z nimi:

get_all - Zwróci to wszystkie obiekty taksonomii tego typu w DDB.

search - Zwróci listę obiektów taksonomii, które pasują do wyszukiwanego terminu.

get - Zwróci to pojedynczy obiekt taksonomii według nazwy lub UUID.

rodzaj źródła

DDB ma taksonomię dla typów źródeł. Ich przykłady obejmują „Założenie”, „wartość pochodną” i „Wytyczne branżowe”.

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

Typ aktywów

DDB ma taksonomię dla typów aktywów. Przykłady obejmują „stronę”, „budynek”, „przestrzeń”, „most”, „tunel” i „droga”.

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

Niektóre typy aktywów mają podtypy. Możesz sprawdzić ich właściwość logiczną asset_sub_type, aby sprawdzić, czy mają podtypy.

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

Podtyp aktywów

Taksonomia DDB potwierdza dalszą klasyfikację typów aktywów na typy podrzędne. Gdy typ aktywów ma typy substancji podrzędne, wszystkie instancje tego typu muszą zostać zaklasyfikowane jako jeden z typów podrzędnych.

Jako przykład „System budowlany” AssetType ma kilka typów Sub, w tym „ogrzewanie”, „chłodzenie” i „oświetlenie”. Wszystkie aktywa tego typu muszą być jednym z tych typów.

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

Typ parametru

DDB ma taksonomię typów parametrów. Przykłady obejmują „letnią temperaturę suchej żarówki”, „Moduł elastyczności”, „Data ostatniej kontroli”.

Służą one do klasyfikacji naszego Parameters i zastosowania niektórych zasad, takich jak jednostki, które mogą mieć lub typy danych, które mogą być.

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

Typ przedmiotu

ItemType to kombinacja AssetType, ParameterType i potencjalnie AssetSubType.

Są one tworzone przez nasz zespół i udostępniają różne ParameterTypes na różnych Assets na podstawie ich AssetType i AssetSubType. Możemy użyć klasy ItemType, aby zobaczyć, które ParameterTypes są dostępne dla różnych 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 pozwala nam zastosować jeszcze bardziej szczegółowe reguły do naszych danych, takie jak lista dostępnych Options. Na przykład może istnieć ItemType, który reprezentuje ParameterType „Typ pola” na stronie AssetType „”. To ItemType może mieć listę Options, która reprezentuje różne typy pól, które można wybrać, takie jak „Brownfield” lub „Greenfield”. Oznaczałoby to, że w DDB wszystkie wartości aktywa „typu pola” na „witrynie” musiałyby być jedną z tych dwóch opcji.

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

Opcja

Option jest wartością, którą można wybrać dla Parameter określonego ItemType. Są to wstępne listy wartości, które są dozwolone dla różnych ItemTypes.

Możesz uzyskać dostęp do ich wartości za pośrednictwem właściwości „Wartość”:

for option in options:
    print(option.value)

Typ jednostki

DDB ma taksonomię dla typów jednostek. Ich przykłady obejmują „temperaturę”, „długość”, „obszar” i „objętość”.

Pozwalają nam grupować jednostki, które są podobne, takie jak „Celsjusz” i „Fahrenheita”, które są w typie „temperatury”. ParameterTypes mają właściwość unit_type, która służy do ograniczenia jednostek, które można użyć do tego 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

Możesz także odzyskać wszystkie jednostki dla danego UnitType.

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

System jednostkowy

DDB ma taksonomię dla systemów jednostkowych. Przykłady obejmują „si”, „imperialne” i „ogólne”.

Pozwalają nam dalej klasyfikować nasze jednostki.

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

Możesz także odzyskać wszystkie jednostki dla danego UnitSystem.

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

Jednostka

DDB ma taksonomię dla jednostek. Przykłady obejmują „M”, „Kg” i „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

Typ roli

Typy ról definiują różne rodzaje dostępu do projektu DDB. Jeden użytkownik może mieć wiele ról.

Różne typy ról to:

Admin - do modyfikowania uprawnień użytkownika

Reader - do czytania danych projektu

Editor - do edytowania danych projektu

Checker - Do aktualizacji statusu QA

Approver - do zatwierdzenia danych

RoleType jest obiektem Enum.

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]'),
])

Etykietka

Tags są używane do uporządkowania naszych danych i mogą być przydatne do filtrowania i wyszukiwania. Przykłady obejmują „Google”, „Szkocja” i „Mechanical”.

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])

Typ tagu

Tags są zgrupowane razem przez TagTypes. Ich przykłady obejmują „klient”, „region” i „scena robocza”.

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()