mapteksdk.data.containers module

Container data types.

Containers are objects which hold other objects. They are used to organise data into a hierarchical structure. A container may have children objects, each of which has a name. Containers may contain other containers, allowing for an arbitrarily nested structure.

class Container(object_id=None, lock_type=LockType.READ)

Bases: DataObject

Plain container object that nests other objects.

It is used to organise data in a hierarchical structure. It is similar to a directory or folder concept in file systems. This type of container can not be viewed. If you are looking to create a container then you likely want to create a VisualContainer.

The same object can be in the same container multiple times with different names.

The same name cannot be used multiple times in the same container.

allow_hidden_objects: bool = False

Allow the SDK to list and create objects considered hidden.

The names of hidden objects start with a full stop (e.g. “.hidden”).

Warning

This should be configured prior to reading the children of the container.

Setting allow_hidden_objects to True and deleting hidden containers that you didn’t create may cause tools in the application to fail and can cause the application to crash.

allow_standard_containers: bool = False

Allow the SDK to handle standard containers like any other containers.

This disables the handling of standard containers as they appear to users.

If False (default), standard containers cannot be added or removed. If True, standard containers are treated as normal containers.

Warning

This should be configured prior to modifying the children of the container.

Setting allow_standard_containers to True and deleting standard containers can cause the application to crash.

classmethod static_type()

Return the type of container as stored in a Project.

This can be used for determining if the type of an object is a container.

cancel()

Cancel any pending changes to the object.

Raises:

ReadOnlyError – If the object was open for read only (i.e not for editing). It is not necessary to call this for a read only object as there will be no pending changes.

property id: ObjectID[Container]

Object ID that uniquely references this object in the project.

Returns:

The unique id of this object.

Return type:

ObjectID

names()

Returns the names of the children.

Returns:

List of names of children.

Return type:

list

ids()

Returns the object IDs of the children.

Returns:

List of ObjectIDs of the children.

Return type:

list

items()

Return the (name, object ID) pair for each child.

Returns:

List of tuples in the form (name, object ID).

Return type:

list

append(child)

Append a child to the end of the container.

Any leading or trailing whitespace will be stripped, such whitespace is avoided as it is hard for users to tell two objects apart if the only difference in their name is whitespace.

If the object referred to by the given ObjectID is deleted, the child will not be added to the container on save.

Parameters:

child (tuple[str, mapteksdk.data.objectid.ObjectID]) – The name to give the object and the ID of the object.

Raises:

  • ValueError – If the name is None, the empty string or name contains a new line or slashes (forward and back).

  • ValueError – If there is another object in the container with the given name (after leading and trailing whitespace has been removed).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

insert(index, child)

Insert child before index in the container.

Any leading or trailing whitespace will be stripped, such whitespace is avoided as it is hard for users to tell two objects apart if the only difference in their name is whitespace.

Parameters:

  • index (int) – The position of where the child should be inserted.

  • child (tuple[str, mapteksdk.data.objectid.ObjectID]) – The name to give the object and the ID of the object.

Raises:

  • ValueError – If the name is None, the empty string or name contains a new line or slashes (forward and back).

  • ValueError – If there is another object in the container with the given name (after leading and trailing whitespace has been removed).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

remove(name)

Remove the child with the given name or object ID from the container.

The name itself won’t be validated to reject names that aren’t possible for a child.

Returns:

The ID of the removed object.

Return type:

ObjectID

Raises:

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

  • KeyError – If there is no child with the given name in the container.

  • ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).

  • ValueError – If the given name is a standard container allow_standard_containers is False (default).

Parameters:

name (str) –

remove_object(object_to_remove)

Remove the first child with object ID from the container.

Only the first occurrence of the object will be removed.

Raises:

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

  • ValueError – If there is no child with the given object ID in the container.

  • ValueError – If the given object is considered hidden and allow_hidden_objects is False (default).

  • ValueError – If the given object is a standard container allow_standard_containers is False (default).

Parameters:

object_to_remove (ObjectID | DataObject) –

replace(name, new_object)

Replace the object with the given name with a different object.

This is similar to removing the object with the given name and then inserting the new object at its old position/index.

This can be used for overwriting an existing object in a container with another.

If the object referred to by the given ObjectID is deleted, the child will not be added to the container on save.

Parameters:

  • name (str) – The name of the object in the container to replace. This is not the path to the object, only its name. For example, to replace the pointset at the path “cad/pointset”, the name of the object to replace is “pointset”, where as “cad” is the name of the container.

  • new_object (ObjectID | DataObject) – The object to replace with.

Returns:

The ID of the object that was replaced.

Return type:

ObjectID

Raises:

  • KeyError – If there is no child called name (the key) in the container.

  • ValueError – If new_object is not a valid object (it is null).

  • ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).

  • ValueError – If the given object is a standard container and allow_standard_containers is False (default).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

rename(old_name, new_name)

Rename an object within this container.

Renaming an object to its own name has no effect.

Renaming a standard container will create a container with the new name and move the children into the new container unless allow_standard_containers is True. This matches the behaviour of if a user renames the container from the explorer.

Care should be taken when renaming standard containers when allow_standard_containers is True. Avoid renaming standard containers that you did not create (i.e avoid renaming standard containers that are created by the applications themselves).

Warning

If a standard container is renamed when allow_standard_containers is False then you must ensure the changes are saved (no error is raised before it is saved). Failing to do so will result in the objects in the standard container being lost.

Parameters:

  • old_name (str) – The current name of the object to rename. This is not the path to the object, only its name. For example, to rename the pointset at the path “cad/pointset”, the old name of the object would be “pointset”.

  • new_name (str) – The new name for the object.

Raises:

  • KeyError – If there is no child by old_name (the key) in the container.

  • ValueError – If the new_name is not a valid name to change to.

  • ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

clear()

Remove all children from the container.

Any child objects that are not in another container will be deleted.

It is fine to call this function if there are no children in the container. This does not clear any object attributes.

The post condition of this function will be len(self) == 0.

Raises:

ReadOnlyError – If the object was open for read only (i.e not for editing).

name_of_object(object_id)

Return the name of the given object in the container.

Only the name of the first occurrence of the object will be provided.

Parameters:

object_id (ObjectID | DataObject) – The ID of the object to find the name of.

Returns:

The name of the object in this container if found.

Return type:

str

Raises:

ValueError – If there is no child with the given object ID in the container. This will be raised if the object is hidden and allow_hidden_objects is False (default) as it will be as if the object ID didn’t appear.

get()

Return the object ID for the given name in the container.

If there is no such child, the null object ID will be returned or default

Parameters:

  • name (str) – The name of the child to return.

  • default (ObjectID) – The ID to return if there is no object called name in the container.

Returns:

The object ID of the object if found otherwise default.

Return type:

ObjectID

attribute_names()

Returns a list containing the names of all object-level attributes.

Use this to iterate over the object attributes.

Returns:

List containing the attribute names.

Return type:

list

Examples

Iterate over all object attributes of the object stared at “target” and print their values.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("target") as read_object:
...     for name in read_object.attribute_names():
...         print(name, ":", read_object.get_attribute(name))
close()

Closes the object.

This should be called as soon as you are finished working with an object. To avoid needing to remember to call this function, open the object using a with block and project.read(), project.new() or project.edit(). Those functions automatically call this function at the end of the with block.

A closed object cannot be used for further reading or writing. The ID of a closed object may be queried and this can then be used to re-open the object.

property closed: bool

If this object has been closed.

Attempting to read or edit a closed object will raise an ObjectClosedError. Such an error typically indicates an error in the script and should not be caught.

Examples

If the object was opened with the Project.new(), Project.edit() or Project.read() in a “with” block, this will be True until the with block is closed and False afterwards.

>>> with self.project.new("cad/point_set", PointSet) as point_set:
>>>     point_set.points = [[1, 2, 3], [4, 5, 6]]
>>>     print("closed?", point_set.closed)
>>> print("closed?", point_set.closed)
closed? False
closed? True
property created_date: datetime

The date and time (in UTC) of when this object was created.

Returns:

The date and time the object was created. 0:0:0 1/1/1970 if the operation failed.

Return type:

datetime.datetime

delete_all_attributes()

Delete all object attributes attached to an object.

This only deletes object attributes and has no effect on PrimitiveAttributes.

Raises:

RuntimeError – If all attributes cannot be deleted.

delete_attribute(attribute)

Deletes a single object-level attribute.

Deleting a non-existent object attribute will not raise an error.

Parameters:

attribute (str) – Name of attribute to delete.

Returns:

True if the object attribute existed and was deleted; False if the object attribute did not exist.

Return type:

bool

Raises:

RuntimeError – If the attribute cannot be deleted.

get_attribute(name)

Returns the value for the attribute with the specified name.

Parameters:

name (str) – The name of the object attribute to get the value for.

Returns:

The value of the object attribute name. For dtype = datetime.datetime this is an integer representing the number of milliseconds since 1st Jan 1970. For dtype = datetime.date this is a tuple of the form: (year, month, day).

Return type:

ObjectAttributeTypes

Raises:

KeyError – If there is no object attribute called name.

Warning

In the future this function may be changed to return datetime.datetime and datetime.date objects instead of the current representation for object attributes of type datetime.datetime or datetime.date.

get_attribute_type(name)

Returns the type of the attribute with the specified name.

Parameters:

name (str) – Name of the attribute whose type should be returned.

Returns:

The type of the object attribute name.

Return type:

ObjectAttributeDataTypes

Raises:

KeyError – If there is no object attribute called name.

property is_read_only: bool

If this object is read-only.

This will return True if the object was open with Project.read() and False if it was open with Project.edit() or Project.new(). Attempting to edit a read-only object will raise an error.

property lock_type: LockType

Indicates whether operating in read-only or read-write mode.

Use the is_read_only property instead for checking if an object is open for reading or editing.

Returns:

The type of lock on this object. This will be LockType.ReadWrite if the object is open for editing and LockType.Read if the object is open for reading.

Return type:

LockType

property modified_date: datetime

The date and time (in UTC) of when this object was last modified.

Returns:

The date and time this object was last modified. 0:0:0 1/1/1970 if the operation failed.

Return type:

datetime.datetime

save()

Save the changes made to the object.

Generally a user does not need to call this function, because it is called automatically at the end of a with block using Project.new() or Project.edit().

Returns:

The change reasons for the operation. This depends on what changes to the object were saved. If the api_version is less than 1.9, this always returns ChangeReasons.NO_CHANGE.

Return type:

ChangeReasons

set_attribute(name, dtype, data)

Sets the value for the object attribute with the specified name.

This will overwrite any existing attribute with the specified name.

Parameters:

  • name (str) – The name of the object attribute for which the value should be set.

  • dtype (type[Union[NoneType, Type[NoneType], ctypes.c_bool, ctypes.c_byte, ctypes.c_ubyte, ctypes.c_short, ctypes.c_ushort, ctypes.c_long, ctypes.c_ulong, ctypes.c_longlong, ctypes.c_ulonglong, ctypes.c_float, ctypes.c_double, ctypes.c_char_p, datetime.datetime, datetime.date, bool, int, float, str]] | None) – The type of data to assign to the attribute. This should be a type from the ctypes module or datetime.datetime or datetime.date. Passing bool is equivalent to passing ctypes.c_bool. Passing str is equivalent to passing ctypes.c_char_p. Passing int is equivalent to passing ctypes.c_int16. Passing float is equivalent to passing ctypes.c_double.

  • data (Any) – The value to assign to object attribute name. For dtype = datetime.datetime this can either be a datetime object or timestamp which will be passed directly to datetime.utcfromtimestamp(). For dtype = datetime.date this can either be a date object or a tuple of the form: (year, month, day).

Raises:

  • ValueError – If dtype is an unsupported type.

  • TypeError – If value is an inappropriate type for object attribute name.

  • ValueError – If name starts or ends with whitespace or is empty.

  • RuntimeError – If a different error occurs.

Notes

If an error occurs after adding a new object attribute or editing an existing object attribute resulting in save() not being called, the changes to the object attributes can only be undone if the application’s API version is 1.6 or greater.

Prior to mapteksdk 1.6: Adding new object attributes, or editing the values of object attributes, will not be undone if an error occurs.

Examples

Create an object attribute on an object at “target” and then read its value.

>>> import ctypes
>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("target") as edit_object:
...     edit_object.set_attribute("count", ctypes.c_int16, 0)
... with project.read("target") as read_object:
...     print(read_object.get_attribute("count"))
0
class VisualContainer(object_id=None, lock_type=LockType.READ)

Bases: Container

A container whose content is intended to be spatial in nature and can be viewed.

This is the typical container object that users create and see in the explorer.

The container can be added to a view. Any applicable children in the container will also appear in the view.

Examples

Create a container with a child.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import VisualContainer
>>> project = Project()
>>> with project.new("example", VisualContainer) as container:
...     with project.new(None, VisualContainer) as child:
...        pass
...     container.append(('child', child.id))

List the children of the root container.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read(project.root_id) as container:
...     for name, object_id in container.items():
...          print(name, object_id)

Query the object ID of the cad container in the root container.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read(project.root_id) as container:
...     print(container["cad"])
classmethod static_type()

Return the type of visual container as stored in a Project.

This can be used for determining if the type of an object is a visual container.

property id: ObjectID[VisualContainer]

Object ID that uniquely references this object in the project.

Returns:

The unique id of this object.

Return type:

ObjectID

allow_hidden_objects: bool = False

Allow the SDK to list and create objects considered hidden.

The names of hidden objects start with a full stop (e.g. “.hidden”).

Warning

This should be configured prior to reading the children of the container.

Setting allow_hidden_objects to True and deleting hidden containers that you didn’t create may cause tools in the application to fail and can cause the application to crash.

allow_standard_containers: bool = False

Allow the SDK to handle standard containers like any other containers.

This disables the handling of standard containers as they appear to users.

If False (default), standard containers cannot be added or removed. If True, standard containers are treated as normal containers.

Warning

This should be configured prior to modifying the children of the container.

Setting allow_standard_containers to True and deleting standard containers can cause the application to crash.

append(child)

Append a child to the end of the container.

Any leading or trailing whitespace will be stripped, such whitespace is avoided as it is hard for users to tell two objects apart if the only difference in their name is whitespace.

If the object referred to by the given ObjectID is deleted, the child will not be added to the container on save.

Parameters:

child (tuple[str, mapteksdk.data.objectid.ObjectID]) – The name to give the object and the ID of the object.

Raises:

  • ValueError – If the name is None, the empty string or name contains a new line or slashes (forward and back).

  • ValueError – If there is another object in the container with the given name (after leading and trailing whitespace has been removed).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

attribute_names()

Returns a list containing the names of all object-level attributes.

Use this to iterate over the object attributes.

Returns:

List containing the attribute names.

Return type:

list

Examples

Iterate over all object attributes of the object stared at “target” and print their values.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("target") as read_object:
...     for name in read_object.attribute_names():
...         print(name, ":", read_object.get_attribute(name))
cancel()

Cancel any pending changes to the object.

Raises:

ReadOnlyError – If the object was open for read only (i.e not for editing). It is not necessary to call this for a read only object as there will be no pending changes.

clear()

Remove all children from the container.

Any child objects that are not in another container will be deleted.

It is fine to call this function if there are no children in the container. This does not clear any object attributes.

The post condition of this function will be len(self) == 0.

Raises:

ReadOnlyError – If the object was open for read only (i.e not for editing).

close()

Closes the object.

This should be called as soon as you are finished working with an object. To avoid needing to remember to call this function, open the object using a with block and project.read(), project.new() or project.edit(). Those functions automatically call this function at the end of the with block.

A closed object cannot be used for further reading or writing. The ID of a closed object may be queried and this can then be used to re-open the object.

property closed: bool

If this object has been closed.

Attempting to read or edit a closed object will raise an ObjectClosedError. Such an error typically indicates an error in the script and should not be caught.

Examples

If the object was opened with the Project.new(), Project.edit() or Project.read() in a “with” block, this will be True until the with block is closed and False afterwards.

>>> with self.project.new("cad/point_set", PointSet) as point_set:
>>>     point_set.points = [[1, 2, 3], [4, 5, 6]]
>>>     print("closed?", point_set.closed)
>>> print("closed?", point_set.closed)
closed? False
closed? True
property created_date: datetime

The date and time (in UTC) of when this object was created.

Returns:

The date and time the object was created. 0:0:0 1/1/1970 if the operation failed.

Return type:

datetime.datetime

delete_all_attributes()

Delete all object attributes attached to an object.

This only deletes object attributes and has no effect on PrimitiveAttributes.

Raises:

RuntimeError – If all attributes cannot be deleted.

delete_attribute(attribute)

Deletes a single object-level attribute.

Deleting a non-existent object attribute will not raise an error.

Parameters:

attribute (str) – Name of attribute to delete.

Returns:

True if the object attribute existed and was deleted; False if the object attribute did not exist.

Return type:

bool

Raises:

RuntimeError – If the attribute cannot be deleted.

get()

Return the object ID for the given name in the container.

If there is no such child, the null object ID will be returned or default

Parameters:

  • name (str) – The name of the child to return.

  • default (ObjectID) – The ID to return if there is no object called name in the container.

Returns:

The object ID of the object if found otherwise default.

Return type:

ObjectID

get_attribute(name)

Returns the value for the attribute with the specified name.

Parameters:

name (str) – The name of the object attribute to get the value for.

Returns:

The value of the object attribute name. For dtype = datetime.datetime this is an integer representing the number of milliseconds since 1st Jan 1970. For dtype = datetime.date this is a tuple of the form: (year, month, day).

Return type:

ObjectAttributeTypes

Raises:

KeyError – If there is no object attribute called name.

Warning

In the future this function may be changed to return datetime.datetime and datetime.date objects instead of the current representation for object attributes of type datetime.datetime or datetime.date.

get_attribute_type(name)

Returns the type of the attribute with the specified name.

Parameters:

name (str) – Name of the attribute whose type should be returned.

Returns:

The type of the object attribute name.

Return type:

ObjectAttributeDataTypes

Raises:

KeyError – If there is no object attribute called name.

ids()

Returns the object IDs of the children.

Returns:

List of ObjectIDs of the children.

Return type:

list

insert(index, child)

Insert child before index in the container.

Any leading or trailing whitespace will be stripped, such whitespace is avoided as it is hard for users to tell two objects apart if the only difference in their name is whitespace.

Parameters:

  • index (int) – The position of where the child should be inserted.

  • child (tuple[str, mapteksdk.data.objectid.ObjectID]) – The name to give the object and the ID of the object.

Raises:

  • ValueError – If the name is None, the empty string or name contains a new line or slashes (forward and back).

  • ValueError – If there is another object in the container with the given name (after leading and trailing whitespace has been removed).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

property is_read_only: bool

If this object is read-only.

This will return True if the object was open with Project.read() and False if it was open with Project.edit() or Project.new(). Attempting to edit a read-only object will raise an error.

items()

Return the (name, object ID) pair for each child.

Returns:

List of tuples in the form (name, object ID).

Return type:

list

property lock_type: LockType

Indicates whether operating in read-only or read-write mode.

Use the is_read_only property instead for checking if an object is open for reading or editing.

Returns:

The type of lock on this object. This will be LockType.ReadWrite if the object is open for editing and LockType.Read if the object is open for reading.

Return type:

LockType

property modified_date: datetime

The date and time (in UTC) of when this object was last modified.

Returns:

The date and time this object was last modified. 0:0:0 1/1/1970 if the operation failed.

Return type:

datetime.datetime

name_of_object(object_id)

Return the name of the given object in the container.

Only the name of the first occurrence of the object will be provided.

Parameters:

object_id (ObjectID | DataObject) – The ID of the object to find the name of.

Returns:

The name of the object in this container if found.

Return type:

str

Raises:

ValueError – If there is no child with the given object ID in the container. This will be raised if the object is hidden and allow_hidden_objects is False (default) as it will be as if the object ID didn’t appear.

names()

Returns the names of the children.

Returns:

List of names of children.

Return type:

list

remove(name)

Remove the child with the given name or object ID from the container.

The name itself won’t be validated to reject names that aren’t possible for a child.

Returns:

The ID of the removed object.

Return type:

ObjectID

Raises:

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

  • KeyError – If there is no child with the given name in the container.

  • ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).

  • ValueError – If the given name is a standard container allow_standard_containers is False (default).

Parameters:

name (str) –

remove_object(object_to_remove)

Remove the first child with object ID from the container.

Only the first occurrence of the object will be removed.

Raises:

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

  • ValueError – If there is no child with the given object ID in the container.

  • ValueError – If the given object is considered hidden and allow_hidden_objects is False (default).

  • ValueError – If the given object is a standard container allow_standard_containers is False (default).

Parameters:

object_to_remove (ObjectID | DataObject) –

rename(old_name, new_name)

Rename an object within this container.

Renaming an object to its own name has no effect.

Renaming a standard container will create a container with the new name and move the children into the new container unless allow_standard_containers is True. This matches the behaviour of if a user renames the container from the explorer.

Care should be taken when renaming standard containers when allow_standard_containers is True. Avoid renaming standard containers that you did not create (i.e avoid renaming standard containers that are created by the applications themselves).

Warning

If a standard container is renamed when allow_standard_containers is False then you must ensure the changes are saved (no error is raised before it is saved). Failing to do so will result in the objects in the standard container being lost.

Parameters:

  • old_name (str) – The current name of the object to rename. This is not the path to the object, only its name. For example, to rename the pointset at the path “cad/pointset”, the old name of the object would be “pointset”.

  • new_name (str) – The new name for the object.

Raises:

  • KeyError – If there is no child by old_name (the key) in the container.

  • ValueError – If the new_name is not a valid name to change to.

  • ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

replace(name, new_object)

Replace the object with the given name with a different object.

This is similar to removing the object with the given name and then inserting the new object at its old position/index.

This can be used for overwriting an existing object in a container with another.

If the object referred to by the given ObjectID is deleted, the child will not be added to the container on save.

Parameters:

  • name (str) – The name of the object in the container to replace. This is not the path to the object, only its name. For example, to replace the pointset at the path “cad/pointset”, the name of the object to replace is “pointset”, where as “cad” is the name of the container.

  • new_object (ObjectID | DataObject) – The object to replace with.

Returns:

The ID of the object that was replaced.

Return type:

ObjectID

Raises:

  • KeyError – If there is no child called name (the key) in the container.

  • ValueError – If new_object is not a valid object (it is null).

  • ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).

  • ValueError – If the given object is a standard container and allow_standard_containers is False (default).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

save()

Save the changes made to the object.

Generally a user does not need to call this function, because it is called automatically at the end of a with block using Project.new() or Project.edit().

Returns:

The change reasons for the operation. This depends on what changes to the object were saved. If the api_version is less than 1.9, this always returns ChangeReasons.NO_CHANGE.

Return type:

ChangeReasons

set_attribute(name, dtype, data)

Sets the value for the object attribute with the specified name.

This will overwrite any existing attribute with the specified name.

Parameters:

  • name (str) – The name of the object attribute for which the value should be set.

  • dtype (type[Union[NoneType, Type[NoneType], ctypes.c_bool, ctypes.c_byte, ctypes.c_ubyte, ctypes.c_short, ctypes.c_ushort, ctypes.c_long, ctypes.c_ulong, ctypes.c_longlong, ctypes.c_ulonglong, ctypes.c_float, ctypes.c_double, ctypes.c_char_p, datetime.datetime, datetime.date, bool, int, float, str]] | None) – The type of data to assign to the attribute. This should be a type from the ctypes module or datetime.datetime or datetime.date. Passing bool is equivalent to passing ctypes.c_bool. Passing str is equivalent to passing ctypes.c_char_p. Passing int is equivalent to passing ctypes.c_int16. Passing float is equivalent to passing ctypes.c_double.

  • data (Any) – The value to assign to object attribute name. For dtype = datetime.datetime this can either be a datetime object or timestamp which will be passed directly to datetime.utcfromtimestamp(). For dtype = datetime.date this can either be a date object or a tuple of the form: (year, month, day).

Raises:

  • ValueError – If dtype is an unsupported type.

  • TypeError – If value is an inappropriate type for object attribute name.

  • ValueError – If name starts or ends with whitespace or is empty.

  • RuntimeError – If a different error occurs.

Notes

If an error occurs after adding a new object attribute or editing an existing object attribute resulting in save() not being called, the changes to the object attributes can only be undone if the application’s API version is 1.6 or greater.

Prior to mapteksdk 1.6: Adding new object attributes, or editing the values of object attributes, will not be undone if an error occurs.

Examples

Create an object attribute on an object at “target” and then read its value.

>>> import ctypes
>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("target") as edit_object:
...     edit_object.set_attribute("count", ctypes.c_int16, 0)
... with project.read("target") as read_object:
...     print(read_object.get_attribute("count"))
0
class StandardContainer(object_id=None, lock_type=LockType.READ)

Bases: VisualContainer

Class for standard containers (such as cad and surfaces).

classmethod static_type()

Return the type of standard container as stored in a Project.

property id: ObjectID[StandardContainer]

Object ID that uniquely references this object in the project.

Returns:

The unique id of this object.

Return type:

ObjectID

allow_hidden_objects: bool = False

Allow the SDK to list and create objects considered hidden.

The names of hidden objects start with a full stop (e.g. “.hidden”).

Warning

This should be configured prior to reading the children of the container.

Setting allow_hidden_objects to True and deleting hidden containers that you didn’t create may cause tools in the application to fail and can cause the application to crash.

allow_standard_containers: bool = False

Allow the SDK to handle standard containers like any other containers.

This disables the handling of standard containers as they appear to users.

If False (default), standard containers cannot be added or removed. If True, standard containers are treated as normal containers.

Warning

This should be configured prior to modifying the children of the container.

Setting allow_standard_containers to True and deleting standard containers can cause the application to crash.

append(child)

Append a child to the end of the container.

Any leading or trailing whitespace will be stripped, such whitespace is avoided as it is hard for users to tell two objects apart if the only difference in their name is whitespace.

If the object referred to by the given ObjectID is deleted, the child will not be added to the container on save.

Parameters:

child (tuple[str, mapteksdk.data.objectid.ObjectID]) – The name to give the object and the ID of the object.

Raises:

  • ValueError – If the name is None, the empty string or name contains a new line or slashes (forward and back).

  • ValueError – If there is another object in the container with the given name (after leading and trailing whitespace has been removed).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

attribute_names()

Returns a list containing the names of all object-level attributes.

Use this to iterate over the object attributes.

Returns:

List containing the attribute names.

Return type:

list

Examples

Iterate over all object attributes of the object stared at “target” and print their values.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("target") as read_object:
...     for name in read_object.attribute_names():
...         print(name, ":", read_object.get_attribute(name))
cancel()

Cancel any pending changes to the object.

Raises:

ReadOnlyError – If the object was open for read only (i.e not for editing). It is not necessary to call this for a read only object as there will be no pending changes.

clear()

Remove all children from the container.

Any child objects that are not in another container will be deleted.

It is fine to call this function if there are no children in the container. This does not clear any object attributes.

The post condition of this function will be len(self) == 0.

Raises:

ReadOnlyError – If the object was open for read only (i.e not for editing).

close()

Closes the object.

This should be called as soon as you are finished working with an object. To avoid needing to remember to call this function, open the object using a with block and project.read(), project.new() or project.edit(). Those functions automatically call this function at the end of the with block.

A closed object cannot be used for further reading or writing. The ID of a closed object may be queried and this can then be used to re-open the object.

property closed: bool

If this object has been closed.

Attempting to read or edit a closed object will raise an ObjectClosedError. Such an error typically indicates an error in the script and should not be caught.

Examples

If the object was opened with the Project.new(), Project.edit() or Project.read() in a “with” block, this will be True until the with block is closed and False afterwards.

>>> with self.project.new("cad/point_set", PointSet) as point_set:
>>>     point_set.points = [[1, 2, 3], [4, 5, 6]]
>>>     print("closed?", point_set.closed)
>>> print("closed?", point_set.closed)
closed? False
closed? True
property created_date: datetime

The date and time (in UTC) of when this object was created.

Returns:

The date and time the object was created. 0:0:0 1/1/1970 if the operation failed.

Return type:

datetime.datetime

delete_all_attributes()

Delete all object attributes attached to an object.

This only deletes object attributes and has no effect on PrimitiveAttributes.

Raises:

RuntimeError – If all attributes cannot be deleted.

delete_attribute(attribute)

Deletes a single object-level attribute.

Deleting a non-existent object attribute will not raise an error.

Parameters:

attribute (str) – Name of attribute to delete.

Returns:

True if the object attribute existed and was deleted; False if the object attribute did not exist.

Return type:

bool

Raises:

RuntimeError – If the attribute cannot be deleted.

get()

Return the object ID for the given name in the container.

If there is no such child, the null object ID will be returned or default

Parameters:

  • name (str) – The name of the child to return.

  • default (ObjectID) – The ID to return if there is no object called name in the container.

Returns:

The object ID of the object if found otherwise default.

Return type:

ObjectID

get_attribute(name)

Returns the value for the attribute with the specified name.

Parameters:

name (str) – The name of the object attribute to get the value for.

Returns:

The value of the object attribute name. For dtype = datetime.datetime this is an integer representing the number of milliseconds since 1st Jan 1970. For dtype = datetime.date this is a tuple of the form: (year, month, day).

Return type:

ObjectAttributeTypes

Raises:

KeyError – If there is no object attribute called name.

Warning

In the future this function may be changed to return datetime.datetime and datetime.date objects instead of the current representation for object attributes of type datetime.datetime or datetime.date.

get_attribute_type(name)

Returns the type of the attribute with the specified name.

Parameters:

name (str) – Name of the attribute whose type should be returned.

Returns:

The type of the object attribute name.

Return type:

ObjectAttributeDataTypes

Raises:

KeyError – If there is no object attribute called name.

ids()

Returns the object IDs of the children.

Returns:

List of ObjectIDs of the children.

Return type:

list

insert(index, child)

Insert child before index in the container.

Any leading or trailing whitespace will be stripped, such whitespace is avoided as it is hard for users to tell two objects apart if the only difference in their name is whitespace.

Parameters:

  • index (int) – The position of where the child should be inserted.

  • child (tuple[str, mapteksdk.data.objectid.ObjectID]) – The name to give the object and the ID of the object.

Raises:

  • ValueError – If the name is None, the empty string or name contains a new line or slashes (forward and back).

  • ValueError – If there is another object in the container with the given name (after leading and trailing whitespace has been removed).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

property is_read_only: bool

If this object is read-only.

This will return True if the object was open with Project.read() and False if it was open with Project.edit() or Project.new(). Attempting to edit a read-only object will raise an error.

items()

Return the (name, object ID) pair for each child.

Returns:

List of tuples in the form (name, object ID).

Return type:

list

property lock_type: LockType

Indicates whether operating in read-only or read-write mode.

Use the is_read_only property instead for checking if an object is open for reading or editing.

Returns:

The type of lock on this object. This will be LockType.ReadWrite if the object is open for editing and LockType.Read if the object is open for reading.

Return type:

LockType

property modified_date: datetime

The date and time (in UTC) of when this object was last modified.

Returns:

The date and time this object was last modified. 0:0:0 1/1/1970 if the operation failed.

Return type:

datetime.datetime

name_of_object(object_id)

Return the name of the given object in the container.

Only the name of the first occurrence of the object will be provided.

Parameters:

object_id (ObjectID | DataObject) – The ID of the object to find the name of.

Returns:

The name of the object in this container if found.

Return type:

str

Raises:

ValueError – If there is no child with the given object ID in the container. This will be raised if the object is hidden and allow_hidden_objects is False (default) as it will be as if the object ID didn’t appear.

names()

Returns the names of the children.

Returns:

List of names of children.

Return type:

list

remove(name)

Remove the child with the given name or object ID from the container.

The name itself won’t be validated to reject names that aren’t possible for a child.

Returns:

The ID of the removed object.

Return type:

ObjectID

Raises:

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

  • KeyError – If there is no child with the given name in the container.

  • ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).

  • ValueError – If the given name is a standard container allow_standard_containers is False (default).

Parameters:

name (str) –

remove_object(object_to_remove)

Remove the first child with object ID from the container.

Only the first occurrence of the object will be removed.

Raises:

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

  • ValueError – If there is no child with the given object ID in the container.

  • ValueError – If the given object is considered hidden and allow_hidden_objects is False (default).

  • ValueError – If the given object is a standard container allow_standard_containers is False (default).

Parameters:

object_to_remove (ObjectID | DataObject) –

rename(old_name, new_name)

Rename an object within this container.

Renaming an object to its own name has no effect.

Renaming a standard container will create a container with the new name and move the children into the new container unless allow_standard_containers is True. This matches the behaviour of if a user renames the container from the explorer.

Care should be taken when renaming standard containers when allow_standard_containers is True. Avoid renaming standard containers that you did not create (i.e avoid renaming standard containers that are created by the applications themselves).

Warning

If a standard container is renamed when allow_standard_containers is False then you must ensure the changes are saved (no error is raised before it is saved). Failing to do so will result in the objects in the standard container being lost.

Parameters:

  • old_name (str) – The current name of the object to rename. This is not the path to the object, only its name. For example, to rename the pointset at the path “cad/pointset”, the old name of the object would be “pointset”.

  • new_name (str) – The new name for the object.

Raises:

  • KeyError – If there is no child by old_name (the key) in the container.

  • ValueError – If the new_name is not a valid name to change to.

  • ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

replace(name, new_object)

Replace the object with the given name with a different object.

This is similar to removing the object with the given name and then inserting the new object at its old position/index.

This can be used for overwriting an existing object in a container with another.

If the object referred to by the given ObjectID is deleted, the child will not be added to the container on save.

Parameters:

  • name (str) – The name of the object in the container to replace. This is not the path to the object, only its name. For example, to replace the pointset at the path “cad/pointset”, the name of the object to replace is “pointset”, where as “cad” is the name of the container.

  • new_object (ObjectID | DataObject) – The object to replace with.

Returns:

The ID of the object that was replaced.

Return type:

ObjectID

Raises:

  • KeyError – If there is no child called name (the key) in the container.

  • ValueError – If new_object is not a valid object (it is null).

  • ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).

  • ValueError – If the given object is a standard container and allow_standard_containers is False (default).

  • ReadOnlyError – If the object was open for read only (i.e not for editing).

save()

Save the changes made to the object.

Generally a user does not need to call this function, because it is called automatically at the end of a with block using Project.new() or Project.edit().

Returns:

The change reasons for the operation. This depends on what changes to the object were saved. If the api_version is less than 1.9, this always returns ChangeReasons.NO_CHANGE.

Return type:

ChangeReasons

set_attribute(name, dtype, data)

Sets the value for the object attribute with the specified name.

This will overwrite any existing attribute with the specified name.

Parameters:

  • name (str) – The name of the object attribute for which the value should be set.

  • dtype (type[Union[NoneType, Type[NoneType], ctypes.c_bool, ctypes.c_byte, ctypes.c_ubyte, ctypes.c_short, ctypes.c_ushort, ctypes.c_long, ctypes.c_ulong, ctypes.c_longlong, ctypes.c_ulonglong, ctypes.c_float, ctypes.c_double, ctypes.c_char_p, datetime.datetime, datetime.date, bool, int, float, str]] | None) – The type of data to assign to the attribute. This should be a type from the ctypes module or datetime.datetime or datetime.date. Passing bool is equivalent to passing ctypes.c_bool. Passing str is equivalent to passing ctypes.c_char_p. Passing int is equivalent to passing ctypes.c_int16. Passing float is equivalent to passing ctypes.c_double.

  • data (Any) – The value to assign to object attribute name. For dtype = datetime.datetime this can either be a datetime object or timestamp which will be passed directly to datetime.utcfromtimestamp(). For dtype = datetime.date this can either be a date object or a tuple of the form: (year, month, day).

Raises:

  • ValueError – If dtype is an unsupported type.

  • TypeError – If value is an inappropriate type for object attribute name.

  • ValueError – If name starts or ends with whitespace or is empty.

  • RuntimeError – If a different error occurs.

Notes

If an error occurs after adding a new object attribute or editing an existing object attribute resulting in save() not being called, the changes to the object attributes can only be undone if the application’s API version is 1.6 or greater.

Prior to mapteksdk 1.6: Adding new object attributes, or editing the values of object attributes, will not be undone if an error occurs.

Examples

Create an object attribute on an object at “target” and then read its value.

>>> import ctypes
>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("target") as edit_object:
...     edit_object.set_attribute("count", ctypes.c_int16, 0)
... with project.read("target") as read_object:
...     print(read_object.get_attribute("count"))
0
class ChildView(children)

Bases: object

Provides a view onto the children of a container.

Iterating over the view will provide both the name and the ID of the objects like the items() function. The container object does not need to remain open to access data in this view. It has cached the data itself. Use Project.get_children() to get a view of the children of a container.

Parameters:

children (list) – List of children to be viewed in the form name, ID.

names()

Returns the names of the children.

Returns:

List of names of children.

Return type:

list

ids()

Returns the object IDs of the children.

Returns:

List of ObjectIDs of the children.

Return type:

list

items()

Return the (name, object ID) pair for each child.

Returns:

List of tuples in the form (name, object ID).

Return type:

list