# Python - PyDDB
Примечание для внешних пользователей - Многие из ссылок в следующем разделе относятся к внутренним приложениям. Пожалуйста, поговорите с командой проекта для поддержки.
Пакет
pyddbобеспечивает четкий способ взаимодействия с DDB путем упрощения синтаксиса и реализации удобных функций.
Это руководство будет охватывать установку и быстрое начало пакета, а также полную ссылку на пакет и его функции.
# Функции
Помимо значительного упрощения интерфейса для взаимодействия с конечными точками API DDB, библиотека предоставляет другие полезные функции:
Аутентификация
Клиент предложит пользователю свои учетные данные ARUP, когда клиент создан создан и автоматически обновляет токен по мере необходимости.
Упрощенный API и реализация
Библиотека создана для начинающих python пользователей, которые хотят создавать автоматические рабочие процессы.
Мы упростили все конечные точки микросервиса в одну библиотеку с последовательным интерфейсом. Это означает, что нужно учиться, и это легко начать.
Вы можете сохранить повторные сценарии, и мы обратимся к проверке дубликатов и выполняем любые обновления для вас. Обычно сценарии можно использовать в других проектах, просто изменяя номер проекта.
Легко исследовать таксономию DDB
У DDB есть собственная таксономия: вы не можете просто создать новый тип активов или параметров.
Эта библиотека предоставляет способы поиска через нашу существующую таксономию по имени или UUID.
Полностью протестирован
Эта библиотека полностью проверяется на текущих и будущих версиях API DDB, так что вы можете начать с уверенностью.
Страница
По умолчанию наши конечные точки возвращают первую страницу данных. Эта библиотека обрабатывает страдание и получает все данные для вас.
IDE поддержка
Библиотека полностью напечатана, поэтому вы можете получить автозаполнение и проверку типов в своем IDE.
# Установка и настройка
Требуется Python 3.10+ (App Store) - необходимо для запуска пакета.
Требуется GIT (Служба) - необходимо для установки пакета.
Требуется учетная запись GitHub с Arup Email - необходимо для установки пакета.
Рекомендуемый код Visual Studio (App Store) - Рекомендуемая среда для написания кода.
После установки вышеперечисленного откройте Visual Studio Code и откройте папку, в которой вы хотите сохранить свою работу.
Откройте терминал Bash и выполните следующие команды:
Создать виртуальную среду
python -m venv .venv
Активировать виртуальную среду
source .venv/Scripts/activate
Установите DDB Python SDK
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/
Установите пакет PyDDB
pip install git+https://github.com/arup-group/PyDDB.git
# Быстрый старт
# Получение данных
Получение данных из DDB так же просто, как и вызов соответствующего метода в объекте проекта.
Это будет обращаться с объектами страдания и возврата с метаданными. Посмотрите на Ссылка на API Чтобы получить больше информации.
Импортируйте части необходимой библиотеки:
from pyddb import DDB, env, Project, ParameterType
Создать экземпляр клиента и установить среду:
ddb = DDB(env.sandbox)
Получите существующий проект DDB:
my_project = Project.get_by_number(project_number="21515700")
Получите данные из проекта:
project_parameters = my_project.get_parameters()
project_assets = my_project.get_assets()
project_sources = my_project.get_sources()
Получите данные из таксономии:
all_parameter_types = ParameterType.get_all()
some_parameter_types = ParameterType.search('area')
my_parameter_type = ParameterType.get("Plot area")
# Публикация данных
Импортируйте части необходимой библиотеки:
from pyddb import DDB, env, Project, ParameterType, AssetType, Unit, Source, Parameter, Asset
Создать экземпляр клиента и установить среду:
ddb = DDB(env.sandbox)
Создайте проект или получите существующий:
project = Project.put("21515700")
Определите активы, которые вы хотите опубликовать:
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,
)
]
Определите параметры, которые вы хотите опубликовать:
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",
),
)
]
Разместите данные:
project.post_assets(assets)
project.post_parameters(parameters)
Каждый из этих методов публикации вернет то, что они публикуют, и не добавляют дубликаты данных. Размещение новых параметров не будет переопределять существующие параметры, если значение, единица или источник не изменились.
Это означает, что эти методы могут быть использованы для создания автоматических рабочих процессов.
# Ссылка на API
Эти документы разбиты классом и дают описание и пример того, как их следует использовать.
В этой библиотеке у нас есть два основных типа классов, которые служат разным целям:
Они представляют значения наших данных и являются тем, что вы будете публиковать и возвращать, чтобы взаимодействовать с данными проекта.
Обычно они будут привязаны к классам таксономии, поэтому мы знаем, с какими данными мы работаем.
Эти классы, такие как «Parametertype» или «Assettype», определяются нашей командой. Это способы классификации наших данных и предоставления им контекста.
Короче говоря, классы данных - это данные, с которыми вы работаете, а классы таксономии - это способы их классификации.
Вы также можете исследовать наши Глоссарий Для получения дополнительной информации об терминах, которые мы используем.
# Классы данных
А DDB и Проект Занятия являются основными точками входа для библиотеки.
Класс DDB используется в каждом скрипте для создания клиента и установления среды.
Класс DDB используется для доступа к данным по проектам, в то время как класс Project используется для доступа к данным по конкретному проекту.
# DDB
Класс DDB является основным классом для клиента. Он используется для создания клиента и установления среды. Все сценарии должны создавать создание клиента с помощью среды, в которой они работают.
from pyddb import DDB, env
ddb_client = DDB(env.sandbox)
Теперь вы можете использовать это для доступа к данным по проектам.
Рекомендуется использовать очень конкретные запросы, чтобы уменьшить объем возвращаемых данных.
all_projects = ddb_client.get_projects()
all_plot_areas = ddb_client.get_parameters(
parameter_type_id=[
ParameterType.get("Plot area").id
]
)
# Проект
Класс проекта используется для доступа к данным по конкретному проекту. Он создается путем передачи номера проекта в методы get_by_number или put.
from pyddb import DDB, env, Project
DDB(env.sandbox)
my_project = Project.get_by_number("00000000")
my_project = Project.put("00000000")
Разница между этими двумя методами заключается в том, что get_by_number вернет проект только в том случае, если он будет существует в DDB. put создаст проект, если его не существует.
# Источник
Исходный класс используется для создания и публикации источников в DDB. Новый источник создается путем передачи типа источника, заголовка и ссылки на метод 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"),
)
Источники могут быть опубликованы в DDB, передавая список источников методу post_sources на Project.
my_project = Project.put("00000000")
my_project.post_sources([my_source])
Источники в проекте могут быть повторно взысканы, позвонив в метод get_sources на Project.
project_sources = my_project.get_sources()
Это означает, что очень легко получить источники из прошлого проекта и повторно использовать их в новом проекте.
# Объект
Класс Asset используется для создания и публикации активов в DDB. Новый актив создается путем передачи имени, типа актива и родителя методу create.
Одна важная вещь, которую следует отметить, заключается в том, что в DDB у вас не может быть двух активов с одним и тем же именем, типом и родителем. Это означает, что у одного сайта не может быть два здания с тем же именем.
Эта библиотека использует эту логику, чтобы предотвратить создание дублирующих активов, и вместо этого будет возвращать существующие активы, если сценарии повторно.
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,
)
Есть несколько правил для создания активов:
Активы нуждаются либо
AssetType, либоAssetSubType, поэтому мы знаем, что это за актив.Активы без
AssetSubTypeнужны имя.Активы должны следовать иерархии типа активов.
Например, актива Building должен иметь актива Site в качестве родителя.
Вы можете изучить класс AssetType, чтобы получить понимание иерархии или использовать пользовательский интерфейс DDB.
Активы могут быть опубликованы в DDB, передавая список активов методу post_assets на Project.
my_project = Project.put("00000000")
my_project.post_assets([my_asset, my_other_asset, yet_another_asset])
Активы на проекте могут быть задержаны, вызывая метод get_assets на Project.
project_assets = my_project.get_assets()
Это означает, что очень легко получить активы из прошлого проекта и повторно использовать их в новом проекте.
# Параметр
Класс Parameter используется для создания и публикации параметров в DDB. Новый параметр создается путем передачи типа параметра, значения, единицы, источника и родителя методу create.
Вы захотите познакомиться с классами Source и Asset перед публикацией параметров.
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,
)
Параметры могут быть размещены в DDB, передавая список параметров методу post_parameters на Project.
my_project = Project.put("00000000")
my_project.post_parameters([my_parameter])
A Parameter может быть создан только с помощью ParameterType, который при публикации создаст пустой параметр без каких -либо значений.
При опубликовании со значением библиотека проверит, изменилось ли значение, единица или источник, и обновляют параметр, если он есть.
Мы также можем опубликовать комментарии вместе с нашими параметрами со значениями.
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.",
)
# Классы таксономии
Эти классы представляют собой различные способы классификации наших данных.
Например, у нас есть тысячи классов данных Parameter в наших проектах, и все они классифицируются по нескольким классам таксономии ParameterType.
Это могут быть сотни Parameter объектов с ParameterType из «области».
Эти классы используются для предоставления контекста для данных, обеспечить его постоянную структуру и облегчить работу.
Все эти классы имеют 3 общих метода, которые вы будете использовать для взаимодействия с ними:
get_all - Это вернет все таксономические объекты такого типа в DDB.
search - Это вернет список объектов таксономии, которые соответствуют поисковому термину.
get - это вернет один объект таксономии по имени или UUID.
# Тип источника
DDB имеет таксономию для типов источников.
Примеры их включают «предположение», «полученную ценность» и «отраслевое руководство».
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```
### Тип актива <a id="asset-type"></a>
DDB имеет таксономию для типов активов.
Примеры их включают «сайт», «здание», «пространство», «мост», «туннель» и «дорога».
```python
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```
Некоторые типы активов имеют подтипы. Вы можете проверить их логическое свойство `asset_sub_type`, чтобы увидеть, есть ли у них подтипы.
```python
if my_asset_type.asset_sub_type:
sub_types = my_asset_type.get_sub_types()
# Подтип актива
Таксономия DDB поддерживает дальнейшую классификацию типов активов по подковым типам.
Когда тип актива имеет подковые типы, все экземпляры такого типа должны быть классифицированы как один из типов.
В качестве примера, «Система строительства» AssetType имеет несколько типов, включая «отопление», «охлаждение» и «освещение».
Все активы этого типа должны быть одним из тех подростков.
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```
### Тип параметра <a id="parameter-type"></a>
DDB имеет таксономию для типов параметров.
Примеры них включают «температуру летней внутренней сухой лампы», «модуль эластичности», «Дата последней проверки».
Они используются для классификации нашего `Parameters` и применения некоторых правил для них, таких как единицы, которые они могут иметь, или типы данных, которыми они могут быть.
```python
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
# Тип вещи
ItemType - это комбинация AssetType, ParameterType и потенциально AssetSubType.
Они создаются нашей командой и делают различные ParameterTypes доступными на разных Assets на основе их AssetType и AssetSubType.
Мы можем использовать класс ItemType, чтобы увидеть, какой ParameterTypes доступен для различных 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 Позвольте нам применять еще более конкретные правила к нашим данным, например, список доступных Options.
Например, может быть ItemType, который представляет тип поля ParameterType 'на сайте AssetType'.
Этот ItemType может иметь список Options, который представляет различные типы полей, которые могут быть выбраны, такие как «Браунфилд» или «Гринфилд».
Это будет означать, что в DDB все значения активов «типа поля» на «сайте» должны быть одним из этих двух вариантов.
for item_type in site_item_types:
if item_type.has_options:
options = item_type.get_options()
# Вариант
Option - это значение, которое можно выбрать для Parameter определенного ItemType.
Это предустановленные списки значений, которые разрешены для разных ItemTypes.
Вы можете получить доступ к их значениям через свойство «стоимость»:
for option in options:
print(option.value)
# Тип блока
DDB имеет таксономию для типов единиц.
Примеры их включают «температуру», «длина», «область» и «объем».
Они позволяют нам группировать подразделения, которые похожи, такие как «Цельсия» и «Фаренгейт», оба находятся в типе «температуры».
ParameterTypes имеет свойство unit_type, которое используется для ограничения единиц, которые можно использовать для этого 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```
Вы также можете получить все единицы для данного `UnitType`.
```python
my_unit_type = UnitType.get('Length')
length_units = my_unit_unit.get_units()
# Единичная система
У DDB есть таксономия для единичных систем.
Примеры их включают «Si», «Imperial» и «General».
Это позволяет нам дополнительно классифицировать наши подразделения.
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
Вы также можете получить все единицы для данного UnitSystem.
my_unit_system = UnitSystem.get('General')
general_units = my_unit_unit.get_units()```
### Единица <a id="unit"></a>
У DDB есть таксономия для подразделений.
Примеры их включают «M», «Kg» и «ft».
```python
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
# Тип роли
Типы ролей определяют различные типы доступа к проекту DDB.
Один пользователь может иметь несколько ролей.
Различные типы ролей:
Admin - Для изменения разрешений пользователей
Reader - для чтения данных проекта
Editor - Для редактирования данных проекта
Checker - для обновления статуса QA
Approver - для утверждения данных
RoleType является объектом 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]'),
])
# Ярлык
Tags используются для организации наших данных и могут быть полезны для фильтрации и поиска.
Примеры их включают «Google», «Scotland» и «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])
# Тип тега
Tags сгруппированы вместе по их TagTypes.
Примеры их включают «Клиент», «Регион» и «Рабочие наставки».
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()