Python - PyDDB

Remarque pour les utilisateurs externes - De nombreux liens de la section suivante se réfèrent aux applications internes. Veuillez parler à votre équipe de projet pour obtenir un soutien.

Le package pyddb fournit un moyen clair pour les non-développeurs d'interagir avec DDB en simplifiant la syntaxe et en implémentant les fonctionnalités de commodité.

Ce guide couvrira l'installation et le démarrage rapide du package, ainsi qu'une référence complète du package et de ses fonctionnalités.

Caractéristiques

En plus de simplifier considérablement l'interface pour interagir avec les points de terminaison de l'API DDB, la bibliothèque fournit d'autres fonctionnalités utiles:

Authentification

Le client invitera l'utilisateur pour ses informations d'identification AUP lorsque le client est instancié et actualisera automatiquement le jeton si nécessaire.

API et implémentation simplifiées

La bibliothèque est conçue pour les utilisateurs débutants Python qui souhaitent créer des workflows automatisés.

Nous avons simplifié tous les points de terminaison de microservice en une seule bibliothèque avec une interface cohérente. Cela signifie qu'il y a moins à apprendre et qu'il est facile de commencer.

Vous pouvez continuer à relancer les scripts et nous gérerons la vérification des doublons et effectuer des mises à jour pour vous. En règle générale, les scripts peuvent être utilisés sur d'autres projets uniquement en modifiant le numéro de projet.

Explorez facilement la taxonomie DDB

DDB a sa propre taxonomie: vous ne pouvez pas simplement créer un nouveau type d'actif ou de paramètre.

Cette bibliothèque fournit des moyens de rechercher dans notre taxonomie existante par nom ou UUID.

Entièrement testé

Cette bibliothèque est entièrement testée avec les versions actuelles et futures de l'API DDB, vous pouvez donc commencer avec confiance.

Pagination

Par défaut, nos points de terminaison renverront la première page des données. Cette bibliothèque gère la pagination et récupère toutes les données pour vous.

Support IDE

La bibliothèque est entièrement tapée, vous pouvez donc obtenir une assurance secours et taper la vérification dans votre IDE.

Installation et configuration

1. Nécessite Python 3.10+ (App Store) - requis pour exécuter le package.
2. Nécessite GIT (Service Desk) - requis pour installer le package.
3. Nécessite un compte GitHub avec ARUP Email - requis pour installer le package.
4. Code Visual Studio recommandé (App Store) - Environnement recommandé pour écrire du code.

Une fois les éléments ci-dessus installés, ouvrez Visual Studio Code et ouvrez un dossier dans lequel vous souhaitez stocker votre travail.

Ouvrez un terminal Bash et exécutez les commandes suivantes :

Créer un environnement virtuel

python -m venv .venv

Activer l'environnement virtuel

source .venv/Scripts/activate

Installez les sdks 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/

Installez le package PyDDB

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

Démarrage rapide

Obtenir des données

L'obtention de données de DDB est aussi simple que d'appeler la méthode appropriée sur l'objet du projet. Cela gérera la pagination et le retour des objets avec des métadonnées. Regarde le Référence de l'API pour plus d'informations.

Importez les parties de la bibliothèque dont vous avez besoin:

from pyddb import DDB, env, Project, ParameterType

Instancier le client et définir l'environnement:

ddb = DDB(env.sandbox)

Obtenez un projet DDB existant:

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

Obtenez des données du projet:

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

Obtenez des données de la taxonomie:

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

Données de publication

Importez les parties de la bibliothèque dont vous avez besoin:

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

Instancier le client et définir l'environnement:

ddb = DDB(env.sandbox)

Créez un projet ou obtenez-en un existant:

project = Project.put("21515700")

Définissez les actifs que vous souhaitez publier:

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

Définissez les paramètres que vous souhaitez publier:

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

Publier les données:

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

Chacune de ces méthodes de poste renverra ce qu'elles publieront et n'ajoutent pas de données en double. La publication de nouveaux paramètres ne remplacera pas les paramètres existants si la valeur, l'unité ou la source n'ont pas changé.

Cela signifie que ces méthodes peuvent être utilisées pour créer des workflows automatisés.

Référence de l'API

Ces documents sont décomposés par classe et fournissent une description et un exemple de la façon dont ils doivent être utilisés. Dans cette bibliothèque, nous avons deux principaux types de classes qui servent des objectifs différents:

Classes de données : Ceux-ci représentent les valeurs de nos données et sont ce que vous publierez et reprenez pour interagir avec les données de votre projet. Ceux-ci seront généralement liés aux classes de taxonomie afin que nous sachions avec quel type de données avec lesquelles nous travaillons.

Cours de taxonomie : Ces classes, telles que «ParameterType» ou «AssetType», sont déterminées par notre équipe. Ce sont des moyens de catégoriser nos données et de lui donner un contexte.

En bref, les classes de données sont les données avec lesquelles vous travaillez, et les classes de taxonomie sont les façons dont nous les classons. Vous pouvez également explorer notre glossaire Pour plus d'informations sur les termes que nous utilisons.

Classes de données

La Le Ddb et Projet Les classes sont les principaux points d'entrée de la bibliothèque. La classe DDB est utilisée dans chaque script pour instancier le client et définir l'environnement. La classe DDB est utilisée pour accéder aux données sur les projets, tandis que la classe Project est utilisée pour accéder aux données sur un projet spécifique.

Ddb

La classe DDB est la classe principale du client. Il est utilisé pour instancier le client et définir l'environnement. Tous les scripts doivent instancier le client dans l'environnement dans lequel il travaille.

from pyddb import DDB, env

ddb_client = DDB(env.sandbox)

Vous pouvez maintenant l'utiliser pour accéder aux données sur les projets. Il est recommandé d'utiliser des requêtes très spécifiques pour réduire la quantité de données renvoyées.

all_projects = ddb_client.get_projects()

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

Projet

La classe de projet est utilisée pour accéder aux données sur un projet spécifique. Il est instancié en passant le numéro de projet aux méthodes get_by_number ou put.

from pyddb import DDB, env, Project

DDB(env.sandbox)

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

La différence entre ces deux méthodes est que get_by_number ne renvoie le projet que s'il existe dans DDB. put créera le projet s'il n'existe pas.

Source

La classe source est utilisée pour créer et publier des sources vers DDB. Une nouvelle source est instanciée en passant le type de source, le titre et la référence à la méthode 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"),
)

Des sources peuvent être publiées sur DDB en passant une liste de sources à la méthode post_sources sur une Project.

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

Les sources sur un projet peuvent être repeivées en appelant la méthode get_sources sur une Project.

project_sources = my_project.get_sources()

Cela signifie qu'il est très facile d'obtenir des sources d'un projet passé et de les réutiliser dans un nouveau projet.

Actif

La classe Asset est utilisée pour créer et publier des actifs vers DDB. Un nouvel actif est instancié en passant le nom, le type d'actif et le parent à la méthode create.

Une chose importante à noter est que dans DDB, vous ne pouvez pas avoir deux actifs avec le même nom, type et parent. Cela signifie qu'un seul site ne peut pas avoir deux bâtiments avec le même nom. Cette bibliothèque utilise cette logique pour empêcher la création d'actifs en double et renvoie à la place les actifs existants si les scripts sont redimensionnés.

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

Il existe quelques règles pour créer des actifs:

• Les actifs ont besoin d'un AssetType, soit d'un AssetSubType afin que nous sachions de quel type d'atout il s'agit.
• Les actifs sans AssetSubType ont besoin d'un nom.
• Les actifs doivent suivre la hiérarchie de type actif. Par exemple, un actif Building doit avoir un actif Site en tant que parent.

Vous pouvez explorer la classe AssetType pour comprendre la hiérarchie ou utiliser l'interface utilisateur DDB.

Les actifs peuvent être publiés sur DDB en passant une liste d'actifs à la méthode post_assets sur une Project.

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

Les actifs sur un projet peuvent être repris en appelant la méthode get_assets sur une Project.

project_assets = my_project.get_assets()

Cela signifie qu'il est très facile d'obtenir des actifs d'un projet passé et de les réutiliser dans un nouveau projet.

Paramètre

La classe Parameter est utilisée pour créer et publier des paramètres à DDB. Un nouveau paramètre est instancié en passant le type de paramètre, la valeur, l'unité, la source et le parent à la méthode create.

Vous voudrez vous familiariser avec les classes Source et Asset_z avant de publier des paramètres.

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

Les paramètres peuvent être publiés sur DDB en passant une liste de paramètres à la méthode post_parameters sur une Project.

my_project = Project.put("00000000")

my_project.post_parameters([my_parameter])

Un Parameter peut être créé avec seulement un ParameterType, qui, une fois publié, créera un paramètre vide sans aucune valeur. Lorsqu'il est affiché avec une valeur, la bibliothèque vérifiera si la valeur, l'unité ou la source ont changé et mettra à jour le paramètre si elle l'a fait.

Nous pouvons également publier des commentaires aux côtés de nos paramètres avec des valeurs.

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

Cours de taxonomie

Ces classes représentent les différentes façons dont nous avons classé nos données.

À titre d'exemple, nous avons des milliers de classes de données Parameter dans nos projets, et ceux-ci sont tous classés par quelques ParameterType classe de taxonomie. Cela pourrait être des centaines d'objets Parameter_z avec les ParameterType de "zone".

Ces classes sont utilisées pour fournir un contexte aux données, lui donner une structure cohérente et faciliter le travail avec.

Toutes ces classes ont 3 méthodes courantes que vous utiliserez pour interagir avec eux:

get_all - Cela rendra tous les objets de taxonomie de ce type dans DDB.

search - Cela renverra une liste d'objets de taxonomie qui correspondent au terme de recherche.

get - Cela renverra un seul objet de taxonomie par son nom ou UUID.

Type de Source

DDB a une taxonomie pour les types de source. Des exemples de ceux-ci incluent «l'hypothèse», la «valeur dérivée» et les «conseils de l'industrie».

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

Type d'actif

DDB a une taxonomie pour les types d'actifs. Des exemples de ceux-ci incluent «Site», «Building», «Space», «Bridge», «Tunnel» et «Road».

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

Certains types d'actifs ont des sous-types. Vous pouvez vérifier leur propriété booléenne asset_sub_type_z pour voir s'ils ont des sous-types.

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

Sous-type d'actif

La taxonomie DDB prend en charge une classification supplémentaire des types d'actifs en sous-types. Lorsqu'un type d'actif a des sous-types, toutes les instances de ce type doivent être classées comme l'un des sous-types.

À titre d'exemple, le «système de construction» AssetType a plusieurs sous-types, y compris «chauffage», «refroidissement» et «éclairage». Tous les actifs de ce type doivent être l'un de ces sous-types.

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

Type de paramètre

DDB a une taxonomie pour les types de paramètres. Des exemples de ceux-ci incluent «la température de l'ampoule sèche d'été», «module d'élasticité», «date de la dernière inspection».

Ceux-ci sont utilisés pour classer notre Parameters et leur appliquer des règles, telles que les unités qu'ils peuvent avoir ou les types de données qu'ils peuvent être.

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

Type d'élément

Un ItemType est une combinaison d'un AssetType, un ParameterType, et potentiellement un AssetSubType.

Ceux-ci sont créés par notre équipe et rendent différents ParameterTypes disponibles sur différents Assets basés sur leur AssetType et AssetSubType. Nous pouvons utiliser la classe ItemType pour voir quelle ParameterTypes est disponible pour différents 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 nous permettent d'appliquer des règles encore plus spécifiques à nos données, telles qu'une liste des Options_z disponibles. Par exemple, il pourrait y avoir un ItemType qui représente le type de champ ParameterType sur le site AssetType '. Ce ItemType pourrait avoir une liste de Options qui représentent les différents types de champs qui peuvent être sélectionnés, tels que 'Brownfield' ou 'Greenfield'. Cela signifierait que dans DDB, toutes les valeurs des actifs de «type de champ» sur le site devraient être l'une de ces deux options.

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

Option

Un Option est une valeur qui peut être sélectionnée pour un Parameter d'un certain ItemType. Ce sont des listes prédéfinies de valeurs autorisées pour différentes ItemTypes.

Vous pouvez accéder à leurs valeurs via la propriété «valeur»:

for option in options:
    print(option.value)

Type d'unité

DDB a une taxonomie pour les types d'unités. Des exemples de ceux-ci incluent «température», «longueur», «zone» et «volume».

Ceux-ci nous permettent de regrouper des unités similaires, comme «Celsius» et «Fahrenheit» étant tous deux dans le type d'unité «température». ParameterTypes Ayez une propriété unit_type qui est utilisée pour restreindre les unités qui peuvent être utilisées pour cela 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

Vous pouvez également récupérer toutes les unités pour un UnitType_z {Z_Button_Z.

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

Système d'unité

DDB a une taxonomie pour les systèmes unitaires. Des exemples de ceux-ci incluent «si», «impérial» et «général».

Ceux-ci nous permettent de classer davantage nos unités.

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

Vous pouvez également récupérer toutes les unités pour un UnitSystem_z {Z_Button_Z.

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

Unité

DDB a une taxonomie pour les unités. Les exemples de ceux-ci incluent «M», «KG» et «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

Type de rôle

Les types de rôles définissent différents types d'accès au projet DDB. Un seul utilisateur peut avoir plusieurs rôles.

Les différents types de rôles sont:

Admin - pour modifier les autorisations utilisateur

Reader - pour lire les données du projet

Editor - pour modifier les données du projet

Checker - pour la mise à jour du statut QA

Approver - pour l'approbation des données

RoleType est un objet 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]'),
])

Étiqueter

Tags sont utilisés pour organiser nos données et peuvent être utiles pour le filtrage et la recherche. Des exemples de ceux-ci incluent «Google», «Écosse» et «Mécanique».

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

Type de balise

Tags sont regroupés par leur TagTypes. Des exemples de ceux-ci incluent «client», «région» et «poste de travail».

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