diff --git a/src/ifcopenshell-python/ifcopenshell/entity_instance.py b/src/ifcopenshell-python/ifcopenshell/entity_instance.py index 7245785e16..ad977e3dc6 100644 --- a/src/ifcopenshell-python/ifcopenshell/entity_instance.py +++ b/src/ifcopenshell-python/ifcopenshell/entity_instance.py @@ -34,21 +34,18 @@ except ImportError as e: class entity_instance(object): - """ - This is the base python class for all IFC objects. + """This is the base Python class for all IFC objects. An instantiated entity_instance will have methods of Python and the IFC class itself. - example: + Example:: - ifc_file = ifcopenshell.open(file_path) - products = ifc_file.by_type("IfcProduct") - - print(products[0].__class__) - >>> - - print(products[0].Representation) - >>> #423=IfcProductDefinitionShape($,$,(#409,#421)) + ifc_file = ifcopenshell.open(file_path) + products = ifc_file.by_type("IfcProduct") + print(products[0].__class__) + >>> + print(products[0].Representation) + >>> #423=IfcProductDefinitionShape($,$,(#409,#421)) """ def __init__(self, e): if isinstance(e, tuple): @@ -93,10 +90,22 @@ class entity_instance(object): return entity_instance.walk(is_instance, unwrap, v) def attribute_type(self, attr): + """Return the data type of a positional attribute of the element + + :param attr: The index of the attribute + :type attr: int + :rtype: string + """ attr_idx = attr if isinstance(attr, numbers.Integral) else self.wrapped_data.get_argument_index(attr) return self.wrapped_data.get_argument_type(attr_idx) def attribute_name(self, attr_idx): + """Return the name of a positional attribute of the element + + :param attr_idx: The index of the attribute + :type attr_idx: int + :rtype: string + """ return self.wrapped_data.get_argument_name(attr_idx) def __setattr__(self, key, value): @@ -147,6 +156,10 @@ class entity_instance(object): return self.wrapped_data.is_a(*args) def id(self): + """Return the STEP numerical identifier + + :rtype: int + """ return self.wrapped_data.id() def __eq__(self, other): @@ -165,18 +178,27 @@ class entity_instance(object): ))) def get_info(self, include_identifier=True, recursive=False, return_type=dict, ignore=()): - """ - Return a dictionary of the entity_instance's properties (Python and IFC) and their values. + """Return a dictionary of the entity_instance's properties (Python and IFC) and their values. - example: + :param include_identifier: Whether or not to include the STEP numerical identifier + :type include_identifier: bool + :param recursive: Whether or not to convert referenced IFC elements into dictionaries too. All attributes also apply recursively + :type recursive: bool + :param return_type: The return data type to be casted into + :type return_type: dict|list|other + :param ignore: A list of attribute names to ignore + :type ignore: set|list + :returns: A dictionary of properties and their corresponding values + :rtype: dict - ifc_file = ifcopenshell.open(file_path) - products = ifc_file.by_type("IfcProduct") - obj_info = products[0].get_info() - print(obj_info.keys()) + Example:: - >>> dict_keys(['Description', 'Name', 'BuildingAddress', 'LongName', 'GlobalId', 'ObjectPlacement', 'OwnerHistory', 'ObjectType', - >>> ...'ElevationOfTerrain', 'CompositionType', 'id', 'Representation', 'type', 'ElevationOfRefHeight']) + ifc_file = ifcopenshell.open(file_path) + products = ifc_file.by_type("IfcProduct") + obj_info = products[0].get_info() + print(obj_info.keys()) + >>> dict_keys(['Description', 'Name', 'BuildingAddress', 'LongName', 'GlobalId', 'ObjectPlacement', 'OwnerHistory', 'ObjectType', + >>> ...'ElevationOfTerrain', 'CompositionType', 'id', 'Representation', 'type', 'ElevationOfRefHeight']) """ def _(): try: diff --git a/src/ifcopenshell-python/ifcopenshell/file.py b/src/ifcopenshell-python/ifcopenshell/file.py index 3390f6a1b1..d74d03d15b 100644 --- a/src/ifcopenshell-python/ifcopenshell/file.py +++ b/src/ifcopenshell-python/ifcopenshell/file.py @@ -36,24 +36,20 @@ except NameError: class file(object): - """ - Base class for containing IFC files. + """Base class for containing IFC files. Class has instance methods for filtering by element Id, Type, etc. - Instantiated objects can be subscripted by Id or Guid - example: + Example:: - ifc_file = ifcopenshell.open(file_path) - products = ifc_file.by_type("IfcProduct") - - print(products[0].id(), products[0].GlobalId) - >>> 122 2XQ$n5SLP5MBLyL442paFx - - # Subscripting - print(products[0] == ifc_file[122] == ifc_file['2XQ$n5SLP5MBLyL442paFx']) - >>> True + ifc_file = ifcopenshell.open(file_path) + products = ifc_file.by_type("IfcProduct") + print(products[0].id(), products[0].GlobalId) + >>> 122 2XQ$n5SLP5MBLyL442paFx + # Subscripting + print(products[0] == ifc_file[122] == ifc_file['2XQ$n5SLP5MBLyL442paFx']) + >>> True """ def __init__(self, f=None, schema=None): if f is not None: @@ -64,6 +60,25 @@ class file(object): self.wrapped_data = ifcopenshell_wrapper.file(*args) def create_entity(self, type, *args, **kwargs): + """Create a new IFC entity in the file. + + :param type: Case insensitive name of the IFC class + :type type: string + :param args: The positional arguments of the IFC class + :param kwargs: The keyword arguments of the IFC class + :returns: An entity instance + :rtype: ifcopenshell.entity_instance.entity_instance + + Example:: + + f = ifcopenshell.file() + f.create_entity('IfcPerson') + >>> #1=IfcPerson($,$,$,$,$,$,$,$) + f.create_entity('IfcPerson', 'Foobar') + >>> #2=IfcPerson('Foobar',$,$,$,$,$,$,$) + f.create_entity('IfcPerson', Identification='Foobar') + >>> #3=IfcPerson('Foobar',$,$,$,$,$,$,$) + """ e = entity_instance((self.schema, type)) self.wrapped_data.add(e.wrapped_data) e.wrapped_data.this.disown() @@ -86,42 +101,73 @@ class file(object): return entity_instance(self.wrapped_data.by_guid(str(key))) def by_id(self, id): - """ - Return IFC objects filtered by IFC ID. + """Return IFC objects filtered by IFC ID. - Returned objects are unwrapped IFC objects. + :param id: STEP numerical identifier + :type id: int + :returns: Returned objects are unwrapped IFC objects. + :rtype: ifcopenshell.entity_instance.entity_instance """ return self[id] def by_guid(self, guid): - """ - Return IFC objects filtered by IFC GUID. + """Return IFC objects filtered by IFC GUID. - Returned objects are unwrapped IFC objects. + :param guid: GlobalId value in 22-character encoded form + :type guid: string + :returns: Returned objects are unwrapped IFC objects. + :rtype: ifcopenshell.entity_instance.entity_instance """ return self[guid] def add(self, inst): + """Undocumented function""" inst.wrapped_data.this.disown() return entity_instance(self.wrapped_data.add(inst.wrapped_data)) def by_type(self, type): - """ - Return IFC objects filtered by IFC Type and wrapped with the entity_instance class. + """Return IFC objects filtered by IFC Type and wrapped with the entity_instance class. - See ifcopenshell.entity_instance for class methods and properties + :param type: The case insensitive type of IFC class to return. + :type type: string + :returns: A list of ifcopenshell.entity_instance.entity_instance objects + :rtype: list """ return [entity_instance(e) for e in self.wrapped_data.by_type(type)] def traverse(self, inst, max_levels=None): + """Get a list of all referenced entities for a particular entity + + :param inst: The entity instance to get all sub instances + :type inst: ifcopenshell.entity_instance.entity_instance + :param max_levels: How far deep to recursively fetch sub instances. None or -1 means infinite. + :type max_levels: None|int + :returns: A list of ifcopenshell.entity_instance.entity_instance objects + :rtype: list + """ if max_levels is None: max_levels = -1 return [entity_instance(e) for e in self.wrapped_data.traverse(inst.wrapped_data, max_levels)] def get_inverse(self, inst): + """Return a list of entities that reference this entity + + :param inst: The entity instance to get inverse relationships + :type inst: ifcopenshell.entity_instance.entity_instance + :returns: A list of ifcopenshell.entity_instance.entity_instance objects + :rtype: list + """ return [entity_instance(e) for e in self.wrapped_data.get_inverse(inst.wrapped_data)] def remove(self, inst): + """Deletes an IFC object in the file. + + Other entities that reference the deleted object will be set to null. + + :param inst: The entity instance to delete + :type inst: ifcopenshell.entity_instance.entity_instance + :rtype: None + """ return self.wrapped_data.remove(inst.wrapped_data) def __iter__(self):