# Python - PyDDB

Catatan untuk pengguna luaran - Banyak pautan dalam bahagian berikut merujuk kepada aplikasi dalaman. Sila bercakap dengan pasukan projek anda untuk mendapat sokongan.

Pakej pyddb menyediakan cara yang jelas bagi bukan pemaju untuk berinteraksi dengan DDB dengan memudahkan sintaks dan melaksanakan ciri-ciri kemudahan.

Panduan ini akan merangkumi pemasangan dan permulaan pakej yang cepat, serta rujukan penuh pakej dan ciri -cirinya.

# ciri-ciri

Selain memudahkan antara muka untuk berinteraksi dengan titik akhir API DDB, perpustakaan menyediakan ciri -ciri berguna yang lain:

Pengesahan

Pelanggan akan meminta pengguna untuk kelayakan ARUP mereka apabila pelanggan ditegaskan dan secara automatik menyegarkan token seperti yang diperlukan.

API dan pelaksanaan yang dipermudahkan

Perpustakaan ini dibina untuk pengguna pemula python yang ingin membuat aliran kerja automatik.

Kami telah mempermudahkan semua titik akhir mikroservis ke dalam perpustakaan tunggal dengan antara muka yang konsisten. Ini bermakna kurang belajar dan mudah dimulakan.

Anda boleh menyimpan skrip semula dan kami akan mengendalikan pemeriksaan untuk pendua dan melakukan kemas kini untuk anda. Biasanya skrip boleh digunakan pada projek lain hanya dengan menukar nombor projek.

Mudah meneroka taksonomi DDB

DDB mempunyai taksonomi sendiri: anda tidak boleh membuat jenis aset atau parameter baru.

Perpustakaan ini menyediakan cara mencari melalui taksonomi sedia ada kami dengan nama atau uuid.

Diuji sepenuhnya

Perpustakaan ini diuji sepenuhnya terhadap versi API DDB semasa dan masa depan, jadi anda boleh memulakan dengan keyakinan.

Penomboran

Secara lalai, titik akhir kami akan mengembalikan halaman pertama data. Perpustakaan ini mengendalikan penomboran dan mengambil semua data untuk anda.

Sokongan IDE

Perpustakaan ini ditaip sepenuhnya, jadi anda boleh mendapatkan autocomplete dan jenis pemeriksaan di IDE anda.

# Pemasangan dan persediaan

Memerlukan Python 3.10+ (App Store) - diperlukan untuk menjalankan pakej.
Memerlukan Git (Meja Perkhidmatan) - diperlukan untuk memasang pakej.
Memerlukan akaun GitHub dengan E -mel Arup - diperlukan untuk memasang pakej.
Kod Visual Studio yang disyorkan (App Store) - Persekitaran yang disyorkan untuk menulis kod.

Sebaik sahaja anda memasang perkara di atas, buka Kod Visual Studio dan buka folder yang anda ingin simpan kerja anda.

Buka terminal Bash dan jalankan arahan berikut:

Mewujudkan persekitaran maya

python -m venv .venv

Aktifkan persekitaran maya

source .venv/Scripts/activate

Pasang 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/

Pasang pakej PyDDB

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

# Permulaan pantas

# Mendapatkan data

Mendapatkan data dari DDB adalah semudah memanggil kaedah yang sesuai pada objek projek. Ini akan mengendalikan penomboran dan kembali objek dengan metadata. Cuba lihat pada Rujukan API untuk maklumat lanjut.

Import bahagian perpustakaan yang anda perlukan:

from pyddb import DDB, env, Project, ParameterType

INTEGANIATE PELANGGAN DAN SETIAP SETEDIA:

ddb = DDB(env.sandbox)

Dapatkan projek DDB yang ada:

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

Dapatkan data dari projek:

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

Dapatkan data dari taksonomi:

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

# Menyiarkan data

Import bahagian perpustakaan yang anda perlukan:

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

INTEGANIATE PELANGGAN DAN SETIAP SETEDIA:

ddb = DDB(env.sandbox)

Buat projek atau dapatkan yang sedia ada:

project = Project.put("21515700")

Tentukan aset yang ingin anda hantar:

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

Tentukan parameter yang ingin anda hantar:

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

Hantarkan data:

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

Setiap kaedah pos ini akan mengembalikan apa yang mereka posting dan tidak menambah data pendua. Menyiarkan parameter baru tidak akan menimpa parameter sedia ada jika nilai, unit, atau sumber tidak berubah.

Ini bermakna kaedah ini boleh digunakan untuk mencipta aliran kerja automatik.

# Rujukan API

Dokumen ini dipecahkan oleh kelas dan memberikan penerangan dan contoh bagaimana ia harus digunakan. Di perpustakaan ini, kami mempunyai dua jenis kelas utama yang melayani tujuan yang berbeza:

Kelas data : Ini mewakili nilai -nilai data kami dan apa yang akan anda posting dan retreiving untuk berinteraksi dengan data projek anda. Ini biasanya akan terikat dengan kelas taksonomi supaya kita tahu jenis data yang kami bekerjasama.

Kelas taksonomi : Kelas -kelas ini, seperti 'ParameterType' atau 'Assettype', ditentukan oleh pasukan kami. Ini adalah cara untuk mengkategorikan data kami dan memberikan konteksnya.

Singkatnya, kelas data adalah data yang anda bekerjasama, dan kelas taksonomi adalah cara kami mengklasifikasikannya. Anda juga boleh meneroka kami GLOSSARY Untuk maklumat lanjut mengenai terma yang kami gunakan.

# Kelas data

The DDB dan Projek Kelas adalah titik kemasukan utama untuk perpustakaan. Kelas DDB digunakan dalam setiap skrip untuk menetapkan pelanggan dan menetapkan persekitaran. Kelas DDB digunakan untuk mengakses data merentasi projek, manakala kelas Project digunakan untuk mengakses data pada projek tertentu.

# DDB

Kelas DDB adalah kelas utama untuk pelanggan. Ia digunakan untuk memberi contoh kepada pelanggan dan menetapkan persekitaran. Semua skrip harus memberi instantiasi pelanggan dengan persekitaran yang mereka kerjakan.

from pyddb import DDB, env

ddb_client = DDB(env.sandbox)

Anda kini boleh menggunakan ini untuk mengakses data merentasi projek. Adalah disyorkan untuk menggunakan pertanyaan yang sangat spesifik untuk mengurangkan jumlah data yang dikembalikan.

all_projects = ddb_client.get_projects()

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

# Projek

Kelas projek digunakan untuk mengakses data pada projek tertentu. Ia ditegaskan dengan lulus nombor projek ke kaedah get_by_number atau put.

from pyddb import DDB, env, Project

DDB(env.sandbox)

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

Perbezaan antara kedua -dua kaedah ini ialah get_by_number hanya akan mengembalikan projek jika ia wujud dalam DDB. put akan membuat projek jika tidak wujud.

# Sumber

Kelas sumber digunakan untuk membuat dan menyiarkan sumber ke DDB. Sumber baru ditegaskan dengan meluluskan jenis sumber, tajuk, dan merujuk kepada kaedah 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"),
)

Sumber boleh diposkan ke DDB dengan lulus senarai sumber ke kaedah post_sources pada Project.

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

Sumber -sumber projek boleh dipulihkan dengan memanggil kaedah get_sources pada Project.

project_sources = my_project.get_sources()

Ini bermakna ia sangat mudah untuk mendapatkan sumber dari projek yang lalu dan menggunakannya semula dalam projek baru.

# Aset

Kelas Asset digunakan untuk membuat dan menyiarkan aset kepada DDB. Aset baru diterapkan dengan lulus nama, jenis aset, dan ibu bapa kepada kaedah create.

Satu perkara penting yang perlu diperhatikan ialah dalam DDB, anda tidak boleh mempunyai dua aset dengan nama, jenis dan ibu bapa yang sama. Ini bermakna bahawa satu laman web tidak boleh mempunyai dua bangunan dengan nama yang sama. Perpustakaan ini menggunakan logik ini untuk mencegah aset pendua daripada dicipta dan sebaliknya akan mengembalikan aset sedia ada jika skrip disusun semula.

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

Terdapat beberapa peraturan untuk membuat aset:

Aset memerlukan sama ada AssetType, atau AssetSubType jadi kita tahu jenis aset itu.
Aset tanpa AssetSubType memerlukan nama.
Aset perlu mengikuti hierarki jenis aset. Sebagai contoh, aset Building perlu mempunyai aset Site sebagai ibu bapa.

Anda boleh meneroka kelas AssetType untuk mendapatkan pemahaman tentang hierarki atau menggunakan UI DDB.

Aset boleh diposkan ke DDB dengan lulus senarai aset ke kaedah post_assets pada Project.

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

Aset pada projek boleh dipulihkan dengan memanggil kaedah get_assets pada Project.

project_assets = my_project.get_assets()

Ini bermakna ia sangat mudah untuk mendapatkan aset dari projek yang lalu dan menggunakan semula mereka dalam projek baru.

# Parameter

Kelas Parameter digunakan untuk membuat dan menyiarkan parameter ke DDB. Parameter baru diterapkan dengan lulus jenis parameter, nilai, unit, sumber, dan ibu bapa kepada kaedah create.

Anda akan mahu mengenali kelas Source dan Asset sebelum menyiarkan parameter.

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

Parameter boleh diposkan ke DDB dengan lulus senarai parameter ke kaedah post_parameters pada Project.

my_project = Project.put("00000000")

my_project.post_parameters([my_parameter])

A Parameter boleh dibuat dengan hanya ParameterType, yang apabila diposkan, akan membuat parameter kosong tanpa sebarang nilai. Apabila diposkan dengan nilai, perpustakaan akan menyemak sama ada nilai, unit, atau sumber telah berubah dan mengemas kini parameter jika ada.

Kami juga boleh menyiarkan komen bersama parameter kami dengan nilai.

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

# Kelas taksonomi

Kelas -kelas ini mewakili cara yang berbeza yang telah kami klasifikasi data kami.

Sebagai contoh, kami mempunyai beribu -ribu kelas data Parameter dalam projek kami, dan ini semua diklasifikasikan oleh beberapa kelas taksonomi ParameterType. Ini boleh beratus -ratus objek Parameter dengan ParameterType "kawasan".

Kelas -kelas ini digunakan untuk memberikan konteks kepada data, memberikan struktur yang konsisten, dan memudahkan untuk bekerja dengan.

Semua kelas ini mempunyai 3 kaedah biasa yang akan anda gunakan untuk berinteraksi dengan mereka:

get_all - Ini akan mengembalikan semua objek taksonomi jenis dalam DDB.

search - Ini akan mengembalikan senarai objek taksonomi yang sepadan dengan istilah carian.

get - Ini akan mengembalikan objek taksonomi tunggal dengan nama atau uuid.

# Jenis sumber

DDB mempunyai taksonomi untuk jenis sumber. Contohnya termasuk 'asumsi', 'nilai yang diperolehi', dan 'bimbingan industri'.

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

# Jenis aset

DDB mempunyai taksonomi untuk jenis aset. Contohnya termasuk 'tapak', 'bangunan', 'ruang', 'jambatan', 'terowong', dan 'jalan'.

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

Sesetengah jenis aset mempunyai subtipe. Anda boleh menyemak harta boolean asset_sub_type mereka untuk melihat sama ada mereka mempunyai subtipe.

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

# Subtipe Aset

Taksonomi DDB menyokong klasifikasi selanjutnya jenis aset ke dalam sub jenis. Apabila jenis aset mempunyai sub jenis, semua contoh jenis itu mesti diklasifikasikan sebagai salah satu jenis sub.

Sebagai contoh, 'sistem bangunan' AssetType mempunyai beberapa sub jenis, termasuk 'pemanasan', 'penyejukan', dan 'pencahayaan'. Semua aset jenis ini perlu menjadi salah satu daripada sub jenis tersebut.

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

# Jenis parameter

DDB mempunyai taksonomi untuk jenis parameter. Contohnya termasuk 'suhu mentol kering dalaman' musim panas ',' modulus keanjalan ',' tarikh pemeriksaan terakhir '.

Ini digunakan untuk mengklasifikasikan Parameters kami dan menggunakan beberapa peraturan kepada mereka, seperti unit yang mereka dapat atau jenis data yang mereka boleh.

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

# Jenis barang

ItemType adalah gabungan AssetType, ParameterType, dan berpotensi AssetSubType.

Ini dicipta oleh pasukan kami dan membuat ParameterTypes berbeza boleh didapati pada Assets yang berbeza berdasarkan AssetType dan AssetSubType mereka. Kita boleh menggunakan kelas ItemType untuk melihat mana ParameterTypes tersedia untuk AssetTypes yang berbeza.

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 Benarkan kami memohon peraturan yang lebih spesifik untuk data kami, seperti senarai Options yang tersedia. Sebagai contoh, terdapat ItemType yang mewakili 'jenis medan' ParameterType di tapak AssetType '. Ini ItemType boleh mempunyai senarai Options yang mewakili pelbagai jenis medan yang boleh dipilih, seperti 'brownfield' atau 'greenfield'. Ini bermakna bahawa dalam DDB, semua nilai 'jenis medan' pada 'tapak' aset harus menjadi salah satu daripada dua pilihan tersebut.

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

# Pilihan

Option adalah nilai yang boleh dipilih untuk Parameter dari ItemType tertentu. Ini adalah senarai pratetap nilai yang dibenarkan untuk ItemTypes yang berbeza.

Anda boleh mengakses nilai mereka melalui harta 'nilai':

for option in options:
    print(option.value)

# Jenis unit

DDB mempunyai taksonomi untuk jenis unit. Contohnya termasuk 'suhu', 'panjang', 'kawasan', dan 'kelantangan'.

Ini membolehkan kita untuk mengumpulkan unit yang sama, seperti 'Celsius' dan 'Fahrenheit' kedua -duanya berada dalam jenis unit 'suhu'. ParameterTypes Mempunyai harta unit_type yang digunakan untuk menyekat unit yang boleh digunakan untuk ParameterType itu.

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

Anda juga boleh mengambil semua unit untuk UnitType yang diberikan.

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

# Sistem unit

DDB mempunyai taksonomi untuk sistem unit. Contohnya termasuk 'Si', 'Imperial', dan 'Umum'.

Ini membolehkan kami mengklasifikasikan lagi unit kami.

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

Anda juga boleh mengambil semua unit untuk UnitSystem yang diberikan.

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

# Unit

DDB mempunyai taksonomi untuk unit. Contohnya termasuk 'm', 'kg', dan '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

# Jenis peranan

Jenis Peranan Menentukan pelbagai jenis akses kepada projek DDB. Pengguna tunggal boleh mempunyai pelbagai peranan.

Jenis peranan yang berbeza adalah:

Admin - untuk mengubahsuai kebenaran pengguna

Reader - untuk membaca data projek

Editor - Untuk mengedit data projek

Checker - Untuk mengemas kini status QA

Approver - untuk meluluskan data

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

# Tag

Tags digunakan untuk mengatur data kami dan boleh berguna untuk penapisan dan pencarian. Contohnya termasuk 'Google', 'Scotland', dan 'Mekanikal'.

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

# Jenis tag

Tags dikelompokkan bersama oleh TagTypes mereka. Contohnya termasuk 'klien', 'rantau', dan 'stesen kerja'.

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

← DDB Grasshopper Postman →