Package pyinventory

Sub-modules

pyinventory.api
pyinventory.client
pyinventory.common
pyinventory.exceptions
pyinventory.graphql
pyinventory.site_survey
pyinventory.site_survey_schema

Classes

class InventoryClient (email: str, password: str, tenant: str = 'fb-test', is_local_host: bool = False, is_dev_mode: bool = False, reporter: gql.gql.reporter.Reporter = <gql.gql.reporter.DummyReporter object>)

This is the class to use for working with inventory. It contains all the functions to query and and edit the inventory.

The init method populates the different entity types for faster run of operations.

Args

email : str
The email of the user to connect with.
password : str
The password of the user to connect with.
tenant : str, optional
The tenant to connect to - should be the beginning of "{}.purpleheadband.cloud" The default is "fb-test" for QA environment
is_local_host : bool, optional
Used for developers to connect to local inventory. This changes the address and also disable verification of ssl certificate
is_dev_mode : bool, optional
Used for developers to connect to local inventory from a container. This changes the address and also disable verification of ssl certificate
reporter : object, optional
Use reporter.InventoryReporter to store reports on all successful and failed mutations in inventory. The default is DummyReporter that discards reports

Ancestors

Methods

def activate_user(client: SymphonyClient, user: User) -> NoneType

Activate the user which would allow the user to login again to symphony

Args

user ( User ): user to activate

Raises

FailedOperationException
internal inventory error

Example

user = client.get_user(email="user@test.com")
client.activate_user(user=user)
def add_customer(client: SymphonyClient, name: str, external_id: Union[str, NoneType]) -> Customer

This function adds Customer.

Args

name : str
name for the Customer
external_id : Optional[str]
external ID for the Customer

Returns

Customer object

Example

new_customers = client.add_customer(name="new_customer")

or

new_customers = client.add_customer(name="new_customer", external_id="12345678")
def add_equipment(client: SymphonyClient, name: str, equipment_type: str, location: Location, properties_dict: Mapping[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]], external_id: Union[str, NoneType] = None) -> Equipment

Create a new equipment in a given location. The equipment will be of the given equipment_type, with the given name and with the given properties. If equipment with this name already exists in this location, then existing equipment is returned.

Args

name : str
new equipment name
equipment_type : str
equipment type name

location ( Location ): location object could be retrieved from - get_location() - add_location()

properties_dict : Mapping[str, PropertyValue]
dictionary of property name to property value
  • str - property name
  • PropertyValue - new value of the same type for this property
external_id : Optional[str]
equipment external ID

Returns

Equipment: You can use the ID to access the equipment from the UI: https://{}.thesymphony.cloud/inventory/inventory?equipment={}

Raises

AssertionException
location contains more than one equipment with the same name or if property value in properties_dict does not match the property type
FailedOperationException
internal inventory error

Example

from datetime import date
equipment = client.add_equipment(
    name="Router X123",
    equipment_type="Router",
    location=location,
    properties_dict={
        "Date Property": date.today(),
        "Lat/Lng Property": (-1.23,9.232),
        "E-mail Property": "user@fb.com",
        "Number Property": 11,
        "String Property": "aa",
        "Float Property": 1.23
    })
def add_equipment_port_type(client: SymphonyClient, name: str, properties: List[PropertyDefinition], link_properties: List[PropertyDefinition]) -> EquipmentPortType

This function creates an equipment port type.

Args

name : str
equipment port type name
properties
(List[ pyinventory.common.data_class.PropertyDefinition ]): list of property definitions
link_properties
(List[ pyinventory.common.data_class.PropertyDefinition ]): list of property definitions

Returns

EquipmentPortType object

Raises

FailedOperationException
internal inventory error

Example

from pyinventory.common.data_class import PropertyDefinition
from pyinventory.graphql.property_kind_enum import PropertyKind
port_type1 = client.add_equipment_port_type(
    name="port type 1",
    properties=[PropertyDefinition(
        property_name="port property",
        property_kind=PropertyKind.string,
        default_value=None,
        is_fixed=True)],
    link_properties=[PropertyDefinition(
        property_name="link port property",
        property_kind=PropertyKind.string,
        default_value=None,
        is_fixed=True)],
)
def add_equipment_to_position(client: SymphonyClient, name: str, equipment_type: str, existing_equipment: Equipment, position_name: str, properties_dict: Mapping[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]], external_id: Union[str, NoneType] = None) -> Equipment

Create a new equipment inside a given position_name of the given existing_equipment. The equipment will be of the given equipment_type, with the given name and with the given properties. If equipment with this name already exists in this position, then existing equipment is returned.

Args

name : str
new equipment name
equipment_type : str
equipment type name

existing_equipment ( Equipment ): could be retrieved from - get_equipment() - get_equipment_in_position() - add_equipment() - add_equipment_to_position()

position_name : str
position name in the equipment type.
properties_dict : Mapping[str, PropertyValue]
dictionary of property name to property value
  • str - property name
  • PropertyValue - new value of the same type for this property
external_id : Optional[str]
equipment external ID

Returns

Equipment object: You can use the ID to access the equipment from the UI: https://{}.thesymphony.cloud/inventory/inventory?equipment={}

Raises

AssertionException
if parent equipment has more than one position with the given name or if property value in properties_dict does not match the property type
FailedOperationException
for internal inventory error

EntityNotFoundError: if existing_equipment does not exist

Example

from datetime import date
equipment = client.add_equipment_to_position(
    name="Card Y123",
    equipment_type="Card",
    existing_equipment=equipment,
    position_name="Pos 1",
    properties_dict={
        "Date Property": date.today(),
        "Lat/Lng Property": (-1.23,9.232),
        "E-mail Property": "user@fb.com",
        "Number Property": 11,
        "String Property": "aa",
        "Float Property": 1.23
    })
def add_equipment_type(client: SymphonyClient, name: str, category: str, properties: Sequence[Tuple[str, str, Union[datetime.date, float, int, str, bool, Tuple[float, float], NoneType], Union[bool, NoneType]]], ports_dict: Dict[str, str], position_list: List[str]) -> EquipmentType

This function creates new equipment type.

Args

name : str
equipment type name
category : str
category name

properties (Sequence[Tuple[str, str, Optional[PropertyValue], Optional[bool]]]): - str - type name - str - enum["string", "int", "bool", "float", "date", "enum", "range", "email", "gps_location", "equipment", "location", "service", "datetime_local"] - PropertyValue - default property value - bool - fixed value flag

ports_dict : Dict[str, str]
dictionary of port name to port type name
  • str - port name
  • str - port type name
position_list : List[str]
list of positions names

Returns

EquipmentType object

Raises

FailedOperationException
internal inventory error

Example

e_type = client.add_equipment_type(
    name="Tp-Link T1600G",
    category="Router",
    properties=[("IP", "string", None, True)],
    ports_dict={"Port 1": "eth port", "port 2": "eth port"},
    position_list=[],
)
def add_file(client: SymphonyClient, local_file_path: str, entity_type: str, entity_id: str, category: Union[str, NoneType] = None) -> NoneType

This function adds file to an entity of a given type.

Args

local_file_path : str
local system path to the file
entity_type : str
one of existing options ["LOCATION", "WORK_ORDER", "SITE_SURVEY", "EQUIPMENT"]
entity_id : string
valid entity ID
category : Optional[string]
file category name

Raises

FailedOperationException
on operation failure

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
client.add_file(
    local_file_path="./document.pdf",
    entity_type="LOCATION",
    entity_id=location.id,
    category="category_name",
)
def add_files(client: SymphonyClient, local_directory_path: str, entity_type: str, entity_id: str, category: Union[str, NoneType] = None) -> NoneType

This function adds all files located in folder to an entity of a given type.

Args

local_directory_path : str
local system path to the directory
entity_type : str
one of existing options ["LOCATION", "WORK_ORDER", "SITE_SURVEY", "EQUIPMENT"]
entity_id : string
valid entity ID
category : Optional[string]
file category name

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
client.add_files(
    local_directory_path="./documents_folder/",
    entity_type="LOCATION",
    entity_id=location.id,
    category="category_name",
)

Connects a link between two ports of two equipments.

Args

equipment_a ( Equipment ): could be retrieved from - get_equipment() - get_equipment_in_position() - add_equipment() - add_equipment_to_position()

port_name_a : str
The name of port in equipment type

equipment_b ( Equipment ): could be retrieved from the following apis: - get_equipment() - get_equipment_in_position() - add_equipment() - add_equipment_to_position()

port_name_b : str
The name of port in equipment type

Returns

Link object

Raises

AssertionError
if port_name in any of the equipment does not exist, or match more than one port or is already occupied by link
FailedOperationException
for internal inventory error

Example

location1 = client.get_location({("Country", "LS_IND_Prod_Copy")})
equipment1 = client.get_equipment(name="indProdCpy1_AIO", location=location1)
location2 = client.get_location({("Country", "LS_IND_Prod")})
equipment2 = client.get_equipment(name="indProd1_AIO", location=location2)
client.add_link(
    equipment_a=equipment1,
    port_name_a="Port A",
    equipment_b=equipment2,
    port_name_b="Port B"
)
def add_location(client: SymphonyClient, location_hirerchy: List[Tuple[str, str]], properties_dict: Dict[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]], lat: Union[float, NoneType] = None, long: Union[float, NoneType] = None, externalID: Union[str, NoneType] = None) -> Location

Create a new location of a specific type with a specific name. It will also get the requested location specifiers for hirerchy leading to it and will create all the hirerchy. However the lat,long and properties_dict would only apply for the last location in the chain. If a location with its name in this place already exists, then existing location is returned

Args

location_hirerchy : List[Tuple[str, str]]
hirerchy of locations.
  • str - location type name
  • str - location name
properties_dict : Dict[str, PropertyValue]
dict of property name to property value. The property value should match the property type, otherwise exception is raised
  • str - property name
  • PropertyValue - new value of the same type for this property
lat : float
latitude
long : float
longitude
externalID : str
location external ID

Returns

Location object

Raises

LocationIsNotUniqueException
if there is two possible locations inside the chain and it is not clear where to create or what to return
FailedOperationException
for internal inventory error

EntityNotFoundError: parent location in the chain does not exist

Example

location = client.add_location(
    location_hirerchy=[
        ("Country", "England"),
        ("City", "Milton Keynes"),
        ("Site", "Bletchley Park")
    ],
    properties_dict={
        "Date Property": date.today(),
        "Lat/Lng Property": (-1.23,9.232),
        "E-mail Property": "user@fb.com",
        "Number Property": 11,
        "String Property": "aa",
        "Float Property": 1.23
    },
    lat=-11.32,
    long=98.32,
    externalID=None)
def add_location_image(client: SymphonyClient, local_file_path: str, location: Location) -> NoneType

This function adds image to existing location.

Args

local_file_path : str
local system path to the file

location ( Location ): existing location object

Raises

FailedOperationException
on operation failure

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
client.add_location_image(
    local_file_path="./document.pdf",
    location=location,
)
def add_location_type(client: SymphonyClient, name: str, properties: List[Tuple[str, str, Union[datetime.date, float, int, str, bool, Tuple[float, float], NoneType], Union[bool, NoneType]]], map_zoom_level: int = 8) -> LocationType

This function creates new location type.

Args

name : str
location type name

properties (List[Tuple[str, str, Optional[PropertyValue], Optional[bool]]]): - str - type name - str - enum["string", "int", "bool", "float", "date", "enum", "range", "email", "gps_location", "equipment", "location", "service", "datetime_local"] - PropertyValue - default property value - bool - fixed value flag

map_zoom_level : int
map zoom level

Returns

LocationType object

Raises

FailedOperationException
internal inventory error

Example

location_type = client.add_location_type(
    name="city",
    properties=[("Contact", "email", None, True)],
    map_zoom_level=5,
)
def add_service(client: SymphonyClient, name: str, external_id: Union[str, NoneType], service_type: str, customer: Union[pyinventory.common.data_class.Customer, NoneType], properties_dict: Dict[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]], links: List[Link]) -> Service
def add_service_endpoint(client: SymphonyClient, service: Service, port: EquipmentPort) -> NoneType
def add_service_type(client: SymphonyClient, name: str, hasCustomer: bool, properties: List[Tuple[str, str, Union[datetime.date, float, int, str, bool, Tuple[float, float], NoneType], Union[bool, NoneType]]]) -> ServiceType
def add_site_survey_image(client: SymphonyClient, local_file_path: str, id: str) -> NoneType

This function adds image to existing site survey.

Args

local_file_path : str
local system path to the file
id : str
site survey ID

Raises

FailedOperationException
on operation failure

Example

client.add_site_survey_image(
    local_file_path="./document.pdf",
    id="123456"
)
def add_user(client: SymphonyClient, email: str, password: str) -> User

Adds new user to inventory with its email and password

Args

email : str
the email address of the user
password : str
password the user would connect with

Returns

User object

Raises

EntityNotFoundError: the user was not created properly
FailedOperationException
internal inventory error
AssertionError
The user was not created for some known reason
HTTPError
Error with connection

Example

user = client.add_user(email="user@test.com", password="P0ssW!rd0f43")
def apply_location_template_to_location(client: SymphonyClient, template_location: Location, location: Location) -> NoneType
def build_site_survey_from_survey_response(survey: SurveyFragment) -> SiteSurvey
def copy_equipment(client: SymphonyClient, equipment: Equipment, dest_location: Location, new_external_id: Union[str, NoneType] = None) -> Equipment

Copy equipment.

Args

equipment ( Equipment ): equipment object to be copied
dest_location ( Location ): destination locatoin to copy to
new_external_id : Optional[str]
equipment external ID

Returns

Equipment object

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
equipment = client.get_equipment(name="indProdCpy1_AIO", location=location)
new_location = client.get_location({("Country", "LS_IND_Prod")})
copied_equipment = client.copy_equipment(
    equipment=equipment,
    dest_location=new_location,
)
def copy_equipment_in_position(client: SymphonyClient, equipment: Equipment, dest_parent_equipment: Equipment, dest_position_name: str, new_external_id: Union[str, NoneType] = None) -> Equipment

Copy equipment in position.

Args

equipment ( Equipment ): equipment object to be copied
dest_parent_equipment ( Equipment ): parent equipment, destination to copy to
dest_position_name : str
destination position name
new_external_id : Optional[str]
new external ID for equipment

Returns

Equipment object

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
equipment_to_copy = client.get_equipment(name="indProdCpy1_AIO", location=location)
parent_equipment = client.get_equipment(name="parent", location=location)
copied_equipment = client.copy_equipment_in_position(
    equipment=equipment,
    dest_parent_equipment=parent_equipment,
    dest_position_name="destination position name",
)
def copy_equipment_type(client: SymphonyClient, curr_equipment_type_name: str, new_equipment_type_name: str) -> EquipmentType

Copy existing equipment type.

Args

curr_equipment_type_name : str
existing equipment type name
new_equipment_type_name : str
new equipment type name

Returns

EquipmentType object

Raises

FailedOperationException
internal inventory error

Example

e_type = client.copy_equipment_type(
    curr_equipment_type_name="Card",
    new_equipment_type_name="External_Card",
)
def copy_equipment_with_all_attachments(client: SymphonyClient, equipment: Equipment, dest_location: Location) -> Dict[EquipmentEquipment]

Copy the equipment to the new location with all its attachments

Args

equipment ( Equipment ): could be retrieved from - get_equipment() - get_equipment_in_position() - add_equipment() - add_equipment_to_position()

dest_location ( Location ): could be retrieved from - get_location() - add_location()

Raises

FailedOperationException
internal inventory error

Returns

Dict[ pyinventory.common.data_class.Equipment , Equipment ] - Equipment - source equipment - Equipment - new equipment

The dict includes the equipment given as parameter and also all the equipments attached to it

def deactivate_user(client: SymphonyClient, user: User) -> NoneType

Deactivate the user which would prevent the user from login in to symphony Users in symphony are never deleted. Only de-activated.

Args: user ( User ): user to deactivate

Raises: FailedOperationException: internal inventory error

Example: user = client.get_user(email="user@test.com") client.deactivate_user(user=user)

def delete_all_equipments(client: SymphonyClient) -> NoneType

This function delete all Equipments.

Example

client.delete_all_equipment()
def delete_customer(client: SymphonyClient, customer: Customer) -> NoneType

This function delete Customer.

Args

customer ( Customer ): customer object

Example

client.delete_customer(customer)
def delete_document(client: SymphonyClient, document: Document) -> NoneType

This function deletes existing document.

Args

document ( Document ): document object

Raises

FailedOperationException
on operation failure

Example

client.delete_document(document=document)
def delete_equipment(client: SymphonyClient, equipment: Equipment) -> NoneType

This function delete Equipment.

Args

equipment ( Equipment ): equipment object

Example

client.delete_equipment(equipment=equipment)
def delete_equipment_port_type(client: SymphonyClient, equipment_port_type_id: str) -> NoneType

This function deletes an equipment port type. It can get only the requested equipment port type ID

Args

equipment_port_type_id : str
equipment port type ID

Example

client.delete_equipment_port_type(equipment_port_type_id=port_type1.id)
def delete_equipment_type_with_equipments(client: SymphonyClient, equipment_type: EquipmentType) -> NoneType

Delete equipment type with existing equipments.

Args

equipment_type ( EquipmentType ): equipment type object

Raises

EntityNotFoundError: if equipment_type does not exist

Example

equipment_type = client.get_or_create_equipment_type(
    name="Tp-Link T1600G",
    category="Router",
    properties=[("IP", "string", None, True)],
    ports_dict={"Port 1": "eth port", "port 2": "eth port"},
    position_list=[],
)
client.delete_equipment_type_with_equipments(equipment_type=equipment_type)
def delete_location(client: SymphonyClient, location: Location) -> NoneType

This delete existing location.

Args

location ( Location ): location object

Raises

EntityNotFoundError: if location does not exist
FailedOperationException
for internal inventory error
LocationCannotBeDeletedWithDependency
if there are dependencies in this location

["files", "images", "children", "surveys", "equipment"]

Example

location = client.get_location(location_hirerchy=[('Site', 'Bletchley Park')])
client.delete_location(location=location)
def delete_location_type_with_locations(client: SymphonyClient, location_type: LocationType) -> NoneType

Delete locaton type with existing locations.

Args

location_type (LocationType): location type object

Raises

EntityNotFoundError: if location_type does not exist

Example

client.delete_location_type_with_locations(location_type=location_type)
def delete_locations_by_location_type(client: SymphonyClient, location_type: LocationType) -> NoneType

Delete locatons by location type.

Args

location_type ( LocationType ): location type object

Raises

EntityNotFoundError: if location_type does not exist

Example

client.delete_locations_by_location_type(location_type=location_type)
def delete_service_type_with_services(client: SymphonyClient, service_type: ServiceType) -> NoneType
def delete_site_survey(client: SymphonyClient, site_survey: SiteSurvey) -> NoneType
def delete_site_survey_image(client: SymphonyClient, survey: SiteSurvey) -> NoneType

This function deletes image from existing site survey.

Args

survey ( SiteSurvey ): site survey object

Raises

FailedOperationException
on operation failure

Example

client.delete_site_survey_image(survey=survey)
def edit_equipment(client: SymphonyClient, equipment: Equipment, new_name: Union[str, NoneType] = None, new_properties: Union[Dict[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]], NoneType] = None) -> Equipment

Edit existing equipment.

Args

equipment ( Equipment ): equipment object
new_name : Optional[str]
equipment new name
new_properties : Optional[Dict[str, PropertyValue]]
dictionary of property name to property value str - property name PropertyValue - new value of the same type for this property

Returns

Equipment object

Raises

FailedOperationException
internal inventory error

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
equipment = client.get_equipment(name="indProdCpy1_AIO", location=location)
edited_equipment = client.edit_equipment(
    equipment=equipment,
    new_name="new_name",
    new_properties={"Z AIO - Number": 123},
)
def edit_equipment_port_type(client: SymphonyClient, port_type: EquipmentPortType, new_name: Union[str, NoneType] = None, new_properties: Union[Dict[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]], NoneType] = None, new_link_properties: Union[Dict[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]], NoneType] = None) -> EquipmentPortType

This function edits an existing equipment port type.

Args

port_type ( EquipmentPortType ): existing eqipment port type object
new_name : str
new name
new_properties
(Dict[str, PropertyValue]): dictionary
  • str - property type name
  • PropertyValue - new value of the same type for this property
new_link_properties
(Dict[str, PropertyValue]): dictionary
  • str - link property type name
  • PropertyValue - new value of the same type for this link property

Returns

EquipmentPortType object

Raises

FailedOperationException
internal inventory error

Example

port_type1 = client.edit_equipment_port_type(
    port_type=equipment_port_type,
    new_name="new port type name",
    new_properties={"existing property name": "new value"},
    new_link_properties={"existing link property name": "new value"},
)
def edit_equipment_type(client: SymphonyClient, name: str, new_positions_list: List[str], new_ports_dict: Dict[str, str]) -> EquipmentType

Edit existing equipment type.

Args

name : str
equipment type name
new_positions_list : List[str]
new position list
new_ports_dict : Dict[str, str]
dictionary of port name to port type name
  • str - port name
  • str - port type name

Returns

EquipmentType object

Raises

FailedOperationException
internal inventory error

Example

edited_equipment = client.edit_equipment_type(
    name="Card",
    new_positions_list=[],
    new_ports_dict={"Port 5": "Z Cards Only (LS - DND)"}
)
def edit_equipment_type_property_type(client: SymphonyClient, equipment_type_name: str, property_type_id: str, new_property_definition: PropertyDefinition) -> EquipmentType

Edit specific property type on specific equipment type.

Args

equipment_type_name : str
existing equipment type name
property_type_name : str
existing property type name

new_property_definition ( PropertyDefinition ): new property definition

Returns

EquipmentType

Raises

EntityNotFoundError: if property type name is not found
FailedOperationException
internal inventory error

Example

e_type = client.edit_equipment_type_property_type_name(
    equipment_type_name="Card",
    property_type_name="contact",
    new_name="contact information",
)

This function returns edited port in equipment based on its name.

Args

equipment ( Equipment ): existing equipment object
port_name : str
existing port name

new_link_properties (Dict[str, PropertyValue]) - str - link property name - PropertyValue - new value of the same type for this property

Returns

EquipmentPort object

Raises

EntityNotFoundError: when EquipmentPortDefinition.port_type_name is None, there are no properties
FailedOperationException
on operation failure

Example

location = client.get_location(location_hirerchy=[("Country", "LS_IND_Prod_Copy")])
equipment = client.get_equipment(name="indProdCpy1_AIO", location=location)
edited_port = client.edit_link_properties(
    equipment=equipment,
    port_name="Z AIO - Port 1",
    new_link_properties={"Link Property 1": 98765},
)
def edit_location(client: SymphonyClient, location: Location, new_name: Union[str, NoneType] = None, new_lat: Union[float, NoneType] = None, new_long: Union[float, NoneType] = None, new_external_id: Union[str, NoneType] = None, new_properties: Union[Dict[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]], NoneType] = None) -> Location

This function returns edited location.

Args

location ( Location ): location object
new_name : Optional[str]
location new name
new_lat : Optional[float]
location new latitude
new_long : Optional[float]
location new longitude
new_external_id : Optional[float]
location new external ID
new_properties : Optional[Dict[str, PropertyValue]]
dictionary of property name to property value
  • str - property name
  • PropertyValue - new value of the same type for this property

Returns

Location object

Raises

FailedOperationException
for internal inventory error

Example

# this call will fail if there is Bletchley Park in two cities
location = client.get_location(location_hirerchy=[("Site", "Bletchley Park")])
edited_location = client.edit_location(
    location=location,
    new_name="New Bletchley Park",
    new_lat=10,
    new_long=20,
    new_external_id=None,
    new_properties={"Contact": "new_contact@info.com"},
)
def edit_port_properties(client: SymphonyClient, equipment: Equipment, port_name: str, new_properties: Dict[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]]) -> EquipmentPort

This function returns edited port in equipment based on its name.

Args

equipment ( Equipment ): existing equipment object
port_name : str
existing port name
new_properties : Dict[str, PropertyValue]
Dict, where
  • str - property name
  • PropertyValue - new value of the same type for this property

Returns

EquipmentPort object

Raises

EntityNotFoundError: when EquipmentPortDefinition.port_type_name is None, there are no properties
or if there any unknown property name in properties_dict keys
FailedOperationException
on operation failure

Example

location = client.get_location(location_hirerchy=[("Country", "LS_IND_Prod_Copy")])
equipment = client.get_equipment(name="indProdCpy1_AIO", location=location)
edited_port = client.edit_port_properties(
    equipment=equipment,
    port_name="Z AIO - Port 1",
    new_properties={"Port Property 2": "test_it"},
)
def edit_user(client: SymphonyClient, user: User, new_password: Union[str, NoneType] = None, new_role: Union[pyinventory.graphql.user_role_enum.UserRole, NoneType] = None) -> NoneType

Edit user password and role

Args

user ( User ): user to edit
new_password : Optional[str]
new password the user would connect with

new_role ( UserRole ): user new role

Raises

FailedOperationException
internal inventory error
AssertionError
The user was not edited for some known reason
HTTPError
Error with connection

Example

user = client.add_user(email="user@test.com", password="P0ssW!rd0f43")
client.edit_user(user=user, new_password="New_Password4Ever", new_role=UserRole.ADMIN)
def get_active_users(client: SymphonyClient) -> List[User]

Get the list of the active users in the system

Returns

List[ pyinventory.common.data_class.User ]

Raises

FailedOperationException
internal inventory error

Example

users = client.get_active_users()
for user in users:
    print(user.email)
def get_all_customers(client: SymphonyClient) -> List[Customer]

This function returns all Customers.

Returns

List[ pyinventory.common.data_class.Customer ]

Example

customers = client.get_all_customers()

Returns all links and port names in equipment.

Args

equipment ( Equipment ): could be retrieved from - get_equipment() - get_equipment_in_position() - add_equipment() - add_equipment_to_position()

Returns

List[Tuple[ pyinventory.common.data_class.Link , str]]:

  • Link - link object
  • str - port definition name

Raises

EntityNotFoundError: if link not found
FailedOperationException
for internal inventory error

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
equipment = client.get_equipment(name="indProdCpy1_AIO", location=location1)
client.get_all_links_and_port_names_of_equipment(equipment=equipment)
def get_equipment(client: SymphonyClient, name: str, location: Location) -> Equipment

Get equipment by name in a given location.

Args

name : str
equipment name

location ( Location): location object could be retrieved from - get_location() - add_location()

Returns

Equipment object: You can use the ID to access the equipment from the UI: https://{}.thesymphony.cloud/inventory/inventory?equipment={}

Raises

EquipmentIsNotUniqueException
location contains more than one equipment with the same name
EquipmentNotFoundException
the equipment was not found
FailedOperationException
internal inventory error

Example

location = client.get_location([("Country", "LS_IND_Prod_Copy")])
equipment = client.get_equipment("indProdCpy1_AIO", location)
def get_equipment_by_external_id(client: SymphonyClient, external_id: str) -> Equipment

Get equipment by external ID.

Args

external_id : str
equipment external ID

Returns

Equipment object: You can use the ID to access the equipment from the UI: https://{}.thesymphony.cloud/inventory/inventory?equipment={}

Raises

EquipmentIsNotUniqueException
location contains more than one equipment with the same external ID
EntityNotFoundError: the equipment was not found
FailedOperationException
internal inventory error

Example

equipment = client.get_equipment_by_external_id(external_id="123456")
def get_equipment_in_position(client: SymphonyClient, parent_equipment: Equipment, position_name: str) -> Equipment

Get the equipment attached in a given position_name of a given parent_equipment

Args

parent_equipment ( Equipment ): could be retrieved from - get_equipment() - get_equipment_in_position() - add_equipment() - add_equipment_to_position()

position_name : str
position name

Returns

Equipment object: You can use the ID to access the equipment from the UI: https://{}.thesymphony.cloud/inventory/inventory?equipment={}

Raises

AssertionException
if parent equipment has more than one position with the given name, or none with this name or if the position is not occupied.
FailedOperationException
for internal inventory error

EntityNotFoundError: if parent_equipment does not exist

Example

location = client.get_location([("Country", "LS_IND_Prod_Copy")])
p_equipment = client.get_equipment("indProdCpy1_AIO", location)
equipment = client.get_equipment_in_position(p_equipment, "some_position")
def get_equipment_port_type(client: SymphonyClient, equipment_port_type_id: str) -> EquipmentPortType

This function returns an equipment port type. It can get only the requested equipment port type ID

Args

equipment_port_type_id : str
equipment port type ID

Returns

EquipmentPortType object

Raises

EntityNotFoundError: equipment port type does not found

Example

port_type = client.get_equipment_port_type(equipment_port_type_id=port_type1.id)
def get_equipment_properties(client: SymphonyClient, equipment: Equipment) -> Dict[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]]

Get specific equipment properties.

Args

equipment ( Equipment ): equipment object

Returns

Dict[str, PropertyValue]
dictionary of property name to property value
  • str - property name
  • PropertyValue - new value of the same type for this property

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
equipment = client.get_equipment("indProdCpy1_AIO", location)
properties = client.get_equipment_properties(equipment=equipment)
def get_equipment_type_of_equipment(client: SymphonyClient, equipment: Equipment) -> EquipmentType

This function returns equipment type object of equipment.

Args

equipment ( Equipment ): equipment object

Returns

EquipmentType object

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
equipment = client.get_equipment(name="indProdCpy1_AIO", location=location)
equipment_type = client.get_equipment_type_of_equipment(equipment=equipment)
def get_equipment_type_property_type(client: SymphonyClient, equipment_type_name: str, property_type_id: str) -> PropertyTypeFragment

Get property type by ID on specific equipment type.

Args

equipment_type_name : str
existing equipment type name
property_type_id : str
property type ID

Returns

PropertyTypeFragment object

Raises

EntityNotFoundError: property type with id=property_type_id is not found

Example

property_type = client.get_equipment_type_property_type(
    equipment_type_name="Card",
    property_type_id="12345",
)
def get_equipment_type_property_type_by_external_id(client: SymphonyClient, equipment_type_name: str, property_type_external_id: str) -> PropertyTypeFragment

Get property type by external ID on specific equipment type.

Args

equipment_type_name : str
existing equipment type name
property_type_external_id : str
property type external ID

Returns

PropertyTypeFragment object

Raises

EntityNotFoundError: property type with external_id=property_type_external_id is not found

Example

property_type = client.get_equipment_type_property_type_by_external_id(
    equipment_type_name="Card",
    property_type_external_id="12345",
)
def get_equipments_by_location(client: SymphonyClient, location_id: str) -> List[Equipment]

Get equipments by ID of specific location.

Args

location_id : str
location ID

Returns

List[ pyinventory.common.data_class.Equipment ]: List of found equipments

Raises

EntityNotFoundError: location with this ID does not exist

Example

equipments = client.get_equipments_by_location(location_id="60129542651")
def get_equipments_by_type(client: SymphonyClient, equipment_type_id: str) -> List[Equipment]

Get equipments by ID of specific type.

Args

equipment_type_id : str
equipment type ID

Returns

List[ pyinventory.common.data_class.Equipment ]: List of found equipments

Raises

EntityNotFoundError: equipment type with this ID does not exist

Example

equipments = client.get_equipments_by_type(equipment_type_id="34359738369")

Returns link in specific port by name in equipment.

Args

equipment ( Equipment ): could be retrieved from - get_equipment() - get_equipment_in_position() - add_equipment() - add_equipment_to_position()

port_name : str
The name of port in equipment type

Returns

Link object

Raises

LinkNotFoundException
if link not found
FailedOperationException
for internal inventory error

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
equipment = client.get_equipment(name="indProdCpy1_AIO", location=location)
client.get_link_in_port_of_equipment(
    equipment=equipment,
    port_name="Port A"
)
def get_location(client: SymphonyClient, location_hirerchy: List[Tuple[str, str]]) -> Location

This function returns a location of a specific type with a specific name. It can get only the requested location specifiers or the hirerchy leading to it

Args

location_hirerchy : List[Tuple[str, str]]
hirerchy of locations
  • str - location type name
  • str - location name

Returns

Location object

Raises

LocationIsNotUniqueException
if there is more than one correct location to return
LocationNotFoundException
if no location was found
EntityNotFoundError: location in the chain does not exist
FailedOperationException
for internal inventory error

Example

location = client.get_location(
    location_hirerchy=[
        ("Country", "England"),
        ("City", "Milton Keynes"),
        ("Site", "Bletchley Park")
    ])

or

# this call will fail if there is Bletchley Park in two cities
location = client.get_location(location_hirerchy=[("Site", "Bletchley Park")])
def get_location_by_external_id(client: SymphonyClient, external_id: str) -> Location

This function returns location by external ID.

Args

external_id : str
location external ID

Returns

Location object

Raises

LocationNotFoundException
location with this external ID does not exists
EntityNotFoundError: location does not found
FailedOperationException
for internal inventory error

Example

location = client.get_location_by_external_id(external_id="12345")
def get_location_children(client: SymphonyClient, location_id: str) -> List[Location]

This function returns all children locations of the given location

Args

location_id : str
parent location ID

Returns

List[ pyinventory.common.data_class.Location ]

Raises

EntityNotFoundError: location does not exist

Example

client.add_location([("Country", "England"), ("City", "Milton Keynes")], {})
client.add_location([("Country", "England"), ("City", "London")], {})
parent_location = client.get_location(location_hirerchy=[("Country", "England")])
children_locations = client.get_location_children(location_id=parent_location.id)
# This call will return a list with 2 locations: "Milton Keynes" and "London"
def get_location_documents(client: SymphonyClient, location: Location) -> List[Document]

This function returns locations documents.

Args

location ( Location ): location object

Returns

List[ pyinventory.common.data_class.Document ]

Raises

EntityNotFoundError: location does not exists
FailedOperationException
for internal inventory error

Example

# this call will fail if there is Bletchley Park in two cities
location = client.get_location(location_hirerchy=[("Site", "Bletchley Park")])
location = client.get_location_documents(location=location)
def get_locations(client: SymphonyClient) -> List[Location]

This function returns all existing locations

Returns

List[ pyinventory.common.data_class.Location ]

Example

all_locations = client.get_locations()
def get_locations_by_external_id(*args: str, **kwargs: int) -> Callable[..., ~ReturnType]
def get_or_create_equipment(client: SymphonyClient, name: str, equipment_type: str, location: Location, properties_dict: Mapping[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]], external_id: Union[str, NoneType] = None) -> Equipment

This function checks equipment existence by name in specific location, in case it is not found by name, creates one.

Args

name : str
equipment name
equipment_type : str
equipment type name

location ( Location ): location object could be retrieved from - get_location() - add_location()

properties_dict : Mapping[str, PropertyValue]
dictionary of property name to property value
  • str - property name
  • PropertyValue - new value of the same type for this property
external_id : Optional[str]
equipment external ID

Returns

Equipment object

Raises

AssertionException
location contains more than one equipment with the same name or if property value in properties_dict does not match the property type
FailedOperationException
internal inventory error

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
equipment = client.get_or_create_equipment(
    name="indProdCpy1_AIO",
    equipment_type="router",
    location=location,
    properties_dict={
        "Date Property": date.today(),
        "Lat/Lng Property": (-1.23,9.232),
        "E-mail Property": "user@fb.com",
        "Number Property": 11,
        "String Property": "aa",
        "Float Property": 1.23
    })
def get_or_create_equipment_in_position(client: SymphonyClient, name: str, equipment_type: str, existing_equipment: Equipment, position_name: str, properties_dict: Mapping[str, Union[datetime.date, float, int, str, bool, Tuple[float, float]]], external_id: Union[str, NoneType] = None) -> Equipment

This function checks equipment existence by name in specific location, in case it is not found by name, creates one.

Args

name : str
equipment name
equipment_type : str
equipment type name
existing_equipment ( Equipment ): existing equipment
position_name : str
position name
properties_dict : Mapping[str, PropertyValue]
dictionary of property name to property value
  • str - property name
  • PropertyValue - new value of the same type for this property
external_id : Optional[str]
equipment external ID

Returns

Equipment object

Raises

AssertionException
location contains more than one equipment with the same name or if property value in properties_dict does not match the property type
FailedOperationException
internal inventory error

Example

location = client.get_location({("Country", "LS_IND_Prod_Copy")})
e_equipment = client.get_equipment(name="indProdCpy1_AIO", location=location)
equipment_in_position = client.get_or_create_equipment_in_position(
    name="indProdCpy1_AIO",
    equipment_type="router",
    existing_equipment=e_equipment,
    position_name="some_position",
    properties_dict={
        "Date Property": date.today(),
        "Lat/Lng Property": (-1.23,9.232),
        "E-mail Property": "user@fb.com",
        "Number Property": 11,
        "String Property": "aa",
        "Float Property": 1.23
    })
def get_or_create_equipment_type(client: SymphonyClient, name: str, category: str, properties: Sequence[Tuple[str, str, Union[datetime.date, float, int, str, bool, Tuple[float, float], NoneType], Union[bool, NoneType]]], ports_dict: Dict[str, str], position_list: List[str]) -> EquipmentType

This function checks equipment type existence, in case it is not found, creates one.

Args

name : str
equipment name
category : str
category name

properties (Sequence[Tuple[str, str, Optional[PropertyValue], Optional[bool]]]): - str - type name - str - enum["string", "int", "bool", "float", "date", "enum", "range", "email", "gps_location", "equipment", "location", "service", "datetime_local"] - PropertyValue - default property value - bool - fixed value flag

ports_dict : Dict[str, str]
dict of property name to property value
  • str - port name
  • str - port type name
position_list : List[str]
list of positions names

Returns

EquipmentType object

Raises

FailedOperationException
internal inventory error

Example

e_type = client.get_or_create_equipment_type(
    name="Tp-Link T1600G",
    category="Router",
    properties=[("IP", "string", None, True)],
    ports_dict={"Port 1": "eth port", "port 2": "eth port"},
    position_list=[],
)
def get_port(client: SymphonyClient, equipment: Equipment, port_name: str) -> EquipmentPort

This function returns port in equipment based on its name.

Args

equipment ( Equipment ): existing equipment object
port_name : str
existing port name

Returns

EquipmentPort object

Raises

EquipmentPortIsNotUniqueException
there is more than one port with this name

EntityNotFoundError: equipment does not exist or port was not found

Example

location = client.get_location(location_hirerchy=[("Country", "LS_IND_Prod_Copy")])
equipment = client.get_equipment(name="indProdCpy1_AIO", location=location)
port = client.get_port(equipment=equipment, port_name="Z AIO - Port 1")
def get_property_type_id(client: SymphonyClient, entity_type: Entity, entity_name: str, property_type_name: str) -> str

Get property type ID on specific entity. entity_type - ["LocationType", "EquipmentType", "ServiceType", "EquipmentPortType"]

Args

entity_type ( Entity ): existing entity type
entity_name : str
existing entity name
property_type_name : str
property type ID

Returns

property type ID (str): property type ID
 

Raises

EntityNotFoundError: if property type with id=property_type_id does not found

Example

property_type = client.get_property_type_id(
    entity_type=Entity.EquipmentType,
    entity_name="Card",
    property_type_name="IP",
)
def get_service(client: SymphonyClient, id: str) -> Service
def get_site_surveys(client: SymphonyClient, location: Location) -> List[SiteSurvey]

Retrieve all site survey completed in the location.

Args

location ( Location ): could be retrieved from getLocation or addLocation api

Returns

List[ pyinventory.common.data_class.SiteSurvey ]

Raises

EntityNotFoundError: location does not exist

def get_user(client: SymphonyClient, email: str) -> User

Returns User object by its email

Args

email : str
the email address the user registered with

Returns

User object

Raises

EntityNotFoundError: the user was not found
FailedOperationException
internal inventory error

Example

user = client.get_user(email="user@test.com")
def get_users(client: SymphonyClient) -> List[User]

Get the list of users in the system (both active and deactivate)

Returns

List[ pyinventory.common.data_class.User ]

Raises

FailedOperationException
internal inventory error

Example

users = client.get_users()
for user in users:
    print(user.email)
def move_location(client: SymphonyClient, location_id: str, new_parent_id: Union[str, NoneType]) -> Location

This function moves existing location to another existing parent location.

Args

location_id : str
existing location ID to be moved
new_parent_id : Optional[str]
new existing parent location ID

Returns

Location object

Raises

FailedOperationException
for internal inventory error

Example

# this call will fail if there is Bletchley Park in two cities
location = client.get_location(location_hirerchy=[("Site", "Bletchley Park")])
moved_location = client.move_locatoin(
    location_id=location.id,
    new_parent_id="12345"
)
def populate_types(self) -> NoneType
def search_for_equipments(client: SymphonyClient, limit: int) -> Tuple[List[Equipment], int]

Search for equipments.

Args

limit : int
search result limit

Returns

Tuple[List[ pyinventory.common.data_class.Equipment ], int]

Example

client.search_for_equipments(limit=10)
def upload_site_survey(client: SymphonyClient, location: Location, name: str, completion_date: datetime.datetime, excel_file_path: str, json_file_path: str) -> NoneType

Upload the site survey to the given completion with the data in the given excel file. We use the schema file to validate the input in the excel is as needed for upload.

Args

location ( Location ): could be retrieved from getLocation or addLocation api
name : str
name of the site survey
completion_date : datetime.datetime object
the time the site survey was completed
excel_file_path : str
the path for the excel with the site survey information The format of this excel should be created by calling site_survey.exportToExcel with the paremeter jsonFilePath (the next parameter of this function)

json_file_path(str): the path for the json file of the schema of the site survey the json file should comply to the schema found in survey_schema.json Example of the format:

{
    "forms": [
    {
        "formTitle": "Site Management - General Information",
        "questions": [
        {
            "questionName": "Exact address",
            "questionType": "TEXT"
        },
        {
            "questionName": "Reference for address",
            "questionType": "TEXT"
        },
        {
            "questionName": "Ubigeo",
            "questionType": "TEXT"
        }
        ]
    }
    ]
}

Raises

AssertionException
if input values in the excel are incorrect
FailedOperationException
internal inventory error