Python - PyDDB

Nota para usuarios externos - Muchos de los enlaces en la siguiente sección se refieren a aplicaciones internas. Hable con su equipo de proyecto para obtener apoyo.

El paquete pyddb proporciona una forma clara para que los no desarrolladores interactúen con DDB simplificando la sintaxis e implementando características de conveniencia.

Esta guía cubrirá la instalación y el inicio rápido del paquete, así como una referencia completa del paquete y sus características.

Características

Además de simplificar enormemente la interfaz para interactuar con los puntos finales de la API DDB, la biblioteca proporciona otras características útiles:

Autenticación

El cliente solicitará al usuario sus credenciales ARUP cuando el cliente esté instanciado y actualice automáticamente el token según sea necesario.

API e implementación simplificadas

La biblioteca está construida para los usuarios principiantes de python que desean crear flujos de trabajo automatizados.

Hemos simplificado todos los puntos finales de microservicio en una sola biblioteca con una interfaz consistente. Esto significa que hay menos que aprender y es fácil comenzar.

Puede mantener los scripts reingresos y manejaremos la verificación de duplicados y realizando cualquier actualización para usted. Por lo general, los scripts se pueden usar en otros proyectos simplemente cambiando el número de proyecto.

Explorar fácilmente la taxonomía de DDB

DDB tiene su propia taxonomía: no puede simplemente crear un nuevo tipo de activo o parámetro.

Esta biblioteca proporciona formas de buscar a través de nuestra taxonomía existente por nombre o UUID.

Totalmente probado

Esta biblioteca se prueba completamente contra versiones actuales y futuras de la API DDB, por lo que puede comenzar con confianza.

Paginación

Por defecto, nuestros puntos finales devolverán la primera página de datos. Esta biblioteca maneja la paginación y recupera todos los datos para usted.

Soporte IDE

La biblioteca está completamente escrita, por lo que puede obtener autocompletar y escribir en su IDE.

Instalación y configuración

1. Requiere Python 3.10+ (App Store) - requerido para ejecutar el paquete.
2. Requiere GIT (escritorio de servicio): requerido para instalar el paquete.
3. Requiere la cuenta GitHub con el correo electrónico ARUP, requerido para instalar el paquete.
4. Código de Visual Studio recomendado (App Store): entorno recomendado para escribir código.

Una vez que haya instalado lo anterior, abra Visual Studio Code y abra una carpeta en la que desee almacenar su trabajo.

Abra una terminal Bash y ejecute los siguientes comandos:

Crear un entorno virtual

python -m venv .venv

Activar el entorno virtual

source .venv/Scripts/activate

Instale los 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 \
ddb-template-service \
-i https://pkgs.dev.azure.com/ovearup/_packaging/ddb/pypi/simple/

Instale el paquete PyDDB

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

Inicio rápido

Obtener datos

Obtener datos de DDB es tan simple como llamar al método apropiado en el objeto del proyecto. Esto manejará los objetos de paginación y devolverá con metadatos. Mira el Referencia de API para más información.

Importar las partes de la biblioteca que necesita:

from pyddb import DDB, env, Project, ParameterType

Instanciar el cliente y establecer el entorno:

ddb = DDB(env.sandbox)

Obtenga un proyecto DDB existente:

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

Obtenga datos del proyecto:

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

Obtenga datos de la taxonomía:

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

Publicación de datos

Importar las partes de la biblioteca que necesita:

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

Instanciar el cliente y establecer el entorno:

ddb = DDB(env.sandbox)

Crear un proyecto o obtener uno existente:

project = Project.put("21515700")

Defina los activos que desea publicar:

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

Defina los parámetros que desea publicar:

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

Publicar los datos:

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

Cada uno de estos métodos de publicación devolverá lo que están publicando y no agregará datos duplicados. Publicar nuevos parámetros no anulará los parámetros existentes si el valor, la unidad o la fuente no han cambiado.

Esto significa que estos métodos se pueden usar para crear flujos de trabajo automatizados.

Referencia de API

Estos documentos se desglosan por clase y proporcionan una descripción y un ejemplo de cómo deben usarse. En esta biblioteca, tenemos dos tipos principales de clases que tienen diferentes propósitos:

Clases de datos : Estos representan los valores de nuestros datos y son lo que publicará y retirará para interactuar con los datos de su proyecto. Por lo general, estos estarán vinculados a las clases de taxonomía para que sepamos con qué tipo de datos estamos trabajando.

Clases de taxonomía : Nuestro equipo determina estas clases, como 'Parametertype' o 'Assettype'. Estas son formas de clasificar nuestros datos y darle contexto.

En resumen, las clases de datos son los datos con los que está trabajando, y las clases de taxonomía son las formas en que lo clasificamos. También puedes explorar nuestro glosario Para obtener más información sobre los términos que utilizamos.

Clases de datos

La El DDB y Proyecto Las clases son los principales puntos de entrada para la biblioteca. La clase DDB se usa en cada script para instanciar el cliente y establecer el entorno. La clase DDB se utiliza para acceder a datos en todos los proyectos, mientras que la clase Project se utiliza para acceder a los datos en un proyecto específico.

DDB

La clase DDB es la clase principal para el cliente. Se utiliza para instanciar al cliente y establecer el entorno. Todos los scripts deben instanciar al cliente con el entorno en el que está trabajando.

from pyddb import DDB, env

ddb_client = DDB(env.sandbox)

Ahora puede usar esto para acceder a datos en todos los proyectos. Se recomienda utilizar consultas muy específicas para reducir la cantidad de datos devueltos.

all_projects = ddb_client.get_projects()

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

Proyecto

La clase de proyecto se utiliza para acceder a los datos en un proyecto específico. Se instancia pasando el número de proyecto a los métodos get_by_number o put.

from pyddb import DDB, env, Project

DDB(env.sandbox)

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

La diferencia entre estos dos métodos es que get_by_number solo devolverá el proyecto si existe en DDB. put creará el proyecto si no existe.

Fuente

La clase fuente se utiliza para crear y publicar fuentes en DDB. Una nueva fuente se instancia al pasar el tipo de fuente, el título y la referencia al método 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"),
)

Las fuentes se pueden publicar en DDB al pasar una lista de fuentes al método post_sources en un Project.

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

Las fuentes en un proyecto se pueden retirar llamando al método get_sources en un Project.

project_sources = my_project.get_sources()

Esto significa que es muy fácil obtener fuentes de un proyecto pasado y reutilizarlas en un nuevo proyecto.

Activo

La clase Asset se usa para crear y publicar activos en DDB. Un nuevo activo se instancia pasando el nombre, el tipo de activo y el padre al método create.

Una cosa importante a tener en cuenta es que en DDB, no puede tener dos activos con el mismo nombre, tipo y padre. Esto significa que un solo sitio no puede tener dos edificios con el mismo nombre. Esta biblioteca utiliza esta lógica para evitar que se creen activos duplicados y, en su lugar, devolverá los activos existentes si los scripts están volviendo a ejecutar.

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

Hay algunas reglas para crear activos:

• Los activos necesitan un AssetType o un AssetSubType para que sepamos qué tipo de activo es.
• Los activos sin un AssetSubType necesitan un nombre.
• Los activos deben seguir la jerarquía de tipo de activo. Por ejemplo, un activo Building debe tener un activo Site como padre.

Puede explorar la clase AssetType para comprender la jerarquía o usar la interfaz de usuario DDB.

Los activos se pueden publicar en DDB pasando una lista de activos al método post_assets en un Project.

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

Los activos en un proyecto se pueden retirar llamando al método get_assets en un Project.

project_assets = my_project.get_assets()

Esto significa que es muy fácil obtener activos de un proyecto pasado y reutilizarlos en un nuevo proyecto.

Parámetro

La clase Parameter se usa para crear y publicar parámetros en DDB. Un nuevo parámetro se instancia pasando el tipo de parámetro, valor, unidad, fuente y padre al método create.

Querrá estar familiarizado con las clases Source y Asset antes de publicar parámetros.

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

Los parámetros se pueden publicar en DDB pasando una lista de parámetros al método post_parameters en un Project.

my_project = Project.put("00000000")

my_project.post_parameters([my_parameter])

Se puede crear un Parameter con solo un ParameterType, que cuando se publique, creará un parámetro en blanco sin ningún valor. Cuando se publica con un valor, la biblioteca verificará si el valor, la unidad o la fuente han cambiado y actualizar el parámetro si lo ha hecho.

También podemos publicar comentarios junto con nuestros parámetros con valores.

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

Clases de taxonomía

Estas clases representan las diferentes formas en que hemos clasificado nuestros datos.

Como ejemplo, tenemos miles de clases de datos Parameter en nuestros proyectos, y todas estas están clasificadas por unas pocas clases de taxonomía ParameterType. Esto podría ser cientos de objetos Parameter con el ParameterType de "área".

Estas clases se utilizan para proporcionar contexto a los datos, brindarle una estructura consistente y facilitar el trabajo.

Todas estas clases tienen 3 métodos comunes que usará para interactuar con ellas:

get_all - Esto devolverá todos los objetos de taxonomía de ese tipo en DDB.

search: esto devolverá una lista de objetos de taxonomía que coincidan con el término de búsqueda.

get - Esto devolverá un objeto de taxonomía único por nombre o UUID.

tipo de fuente

DDB tiene una taxonomía para los tipos de origen. Ejemplos de estos incluyen 'suposición', 'valor derivado' y 'orientación de la industria'.

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

Tipo de activo

DDB tiene una taxonomía para los tipos de activos. Ejemplos de estos incluyen 'Sitio', 'Edificio', 'Espacio', 'Puente', 'Túnel' y '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

Algunos tipos de activos tienen subtipos. Puede consultar su propiedad booleana asset_sub_type para ver si tienen subtipos.

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

Subtipo de activo

La taxonomía de DDB respalda una mayor clasificación de los tipos de activos en subtipos. Cuando un tipo de activo tiene subtipos, todas las instancias de ese tipo deben clasificarse como uno de los subtipos.

Como ejemplo, el 'sistema de construcción' AssetType tiene varios subtipos, que incluyen 'calefacción', 'enfriamiento' e 'iluminación'. Todos los activos de este tipo deben ser uno de esos subtipos.

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

Tipo de parámetro

DDB tiene una taxonomía para los tipos de parámetros. Ejemplos de estos incluyen 'temperatura de la bombilla seca de verano', 'módulo de elasticidad', 'fecha de la última inspección'.

Estos se utilizan para clasificar nuestro Parameters y aplicarles algunas reglas, como las unidades que pueden tener o los tipos de datos que pueden ser.

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

Tipo de artículo

Un ItemType es una combinación de un AssetType, un ParameterType y potencialmente un AssetSubType.

Estos son creados por nuestro equipo y hacen que diferentes ParameterTypes estén disponibles en diferentes Assets en función de su AssetType y AssetSubType. Podemos usar la clase ItemType para ver qué ParameterTypes están disponibles para diferentes 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 Permítanos aplicar reglas aún más específicas a nuestros datos, como una lista de Options disponibles. Por ejemplo, podría haber un ItemType que represente el ParameterType 'tipo de campo' en el AssetType 'Sitio'. Este ItemType podría tener una lista de Options que representan los diferentes tipos de campos que se pueden seleccionar, como 'Brownfield' o 'Greenfield'. Esto significaría que en DDB, todos los valores del "tipo de campo" en los activos del "sitio" tendrían que ser una de esas dos opciones.

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

Opción

Un Option es un valor que se puede seleccionar para un Parameter de cierto ItemType. Estas son listas preestablecidas de valores que están permitidos para diferentes ItemTypes.

Puede acceder a sus valores a través de la propiedad 'Valor':

for option in options:
    print(option.value)

Tipo de unidad

DDB tiene una taxonomía para los tipos de unidades. Ejemplos de estos incluyen 'temperatura', 'longitud', 'área' y 'volumen'.

Estos nos permiten agrupar unidades que son similares, como 'Celsius' y 'Fahrenheit', ambos en el tipo de unidad de 'temperatura'. ParameterTypes tiene una propiedad unit_type que se usa para restringir las unidades que se pueden usar para eso 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

También puede recuperar todas las unidades para un UnitType determinado.

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

Unidad de sistema

DDB tiene una taxonomía para los sistemas unitarios. Ejemplos de estos incluyen 'Si', 'Imperial' y 'General'.

Estos nos permiten clasificar aún más nuestras unidades.

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

También puede recuperar todas las unidades para un UnitSystem determinado.

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

Unidad

DDB tiene una taxonomía para las unidades. Ejemplos de estos incluyen 'm', 'kg' y '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

Tipo de rol

Los tipos de roles definen diferentes tipos de acceso al proyecto DDB. Un solo usuario puede tener múltiples roles.

Los diferentes tipos de roles son:

Admin - para modificar los permisos de los usuarios

Reader - para leer datos del proyecto

Editor - para editar datos del proyecto

Checker - para actualizar el estado de control de calidad

Approver - para aprobar datos

RoleType es un objeto 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]'),
])

Etiqueta

Tags se utilizan para organizar nuestros datos y puede ser útil para filtrar y buscar. Ejemplos de estos incluyen 'Google', 'Escocia' y 'Mecánica'.

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

Tipo de etiqueta

Tags se agrupan por su TagTypes. Ejemplos de estos incluyen 'cliente', 'región' y 'escenario de trabajo'.

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