Module pyinventory.api.location

Functions

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