From b23f4459462c49d2f7d67c47176e6f56a18b78d5 Mon Sep 17 00:00:00 2001 From: Dion Moult Date: Wed, 23 Nov 2022 10:56:12 +0900 Subject: [PATCH] Add API documentation for document module --- .../api/document/add_information.py | 36 ++++++++++++-- .../api/document/add_reference.py | 47 +++++++++++++++++-- .../api/document/assign_document.py | 41 ++++++++++++++-- .../api/document/edit_information.py | 26 ++++++++-- .../api/document/edit_reference.py | 29 ++++++++++-- .../api/document/remove_information.py | 22 +++++++-- .../api/document/remove_reference.py | 21 +++++++-- .../api/document/unassign_document.py | 34 ++++++++++++-- 8 files changed, 222 insertions(+), 34 deletions(-) diff --git a/src/ifcopenshell-python/ifcopenshell/api/document/add_information.py b/src/ifcopenshell-python/ifcopenshell/api/document/add_information.py index d54cede7dc..0d96ba18a2 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/document/add_information.py +++ b/src/ifcopenshell-python/ifcopenshell/api/document/add_information.py @@ -20,11 +20,39 @@ import ifcopenshell class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, parent=None): + """Adds a new document information to the project + + An IFC document information is a document associated with the project. + It may be a drawing, specification, schedule, certificate, warranty + guarantee, manual, contract, and so on. They are often used for drawings + and facility management purposes. + + A document may also be a subdocument of a larger document, this is + useful for superseding documents or tracking older versions. The parent + is considered the latest version and the children are older revisions. + + :param parent: The parent document, if necessary. + :type parent: ifcopenshell.entity_instance.entity_instance, optional + :return: The newly created IfcDocumentInformation entity + :rtype: ifcopenshell.entity_instance.entity_instance + + Example:: + + document = ifcopenshell.api.run("document.add_information", model) + # A document typically has a unique drawing or document name (which + # follows a coding system depending on the project), as well as a + # title. This should match what is shown on the titleblock or title + # page of the document. At a minimum you'd also want to specify a + # URI location. The location may be on local, or on a CDE, or any + # other platform. + ifcopenshell.api.run("document.edit_information", model, + information=document, + attributes={"Identification": "A-GA-6100", "Name": "Overall Plan", + "Location": "A-GA-6100 - Overall Plan.pdf"}) + """ self.file = file - self.settings = {"parent": None} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"parent": parent} def execute(self): id_attribute = "DocumentId" if self.file.schema == "IFC2X3" else "Identification" diff --git a/src/ifcopenshell-python/ifcopenshell/api/document/add_reference.py b/src/ifcopenshell-python/ifcopenshell/api/document/add_reference.py index cd476227bf..f5b24d2cf4 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/document/add_reference.py +++ b/src/ifcopenshell-python/ifcopenshell/api/document/add_reference.py @@ -18,11 +18,50 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, information=None): + """Creates a new reference to a document to assign to products + + A document may be associated with physical products, tasks, cost items, + and so on. For example, spaces, storeys, and buildings may have a list + of associated drawings so you can see which drawings (e.g. plans, + sections, details) are documenting that location. Alternatively, + equipment may have associated training manuals, operation and + maintenance manuals or detailed assembly drawings. Resources may be + training certification required, schedules may have gantt charts or bid + documents, and so on. + + In order to associate a document with an object, a reference to that + document needs to be created. It could be a reference to the entire + document, or a reference to a particular page or chapter. See + ifcopenshell.api.document.assign_document for more information. + + :param information: The IfcDocumentInformation that the reference will + be created for + :type information: ifcopenshell.entity_instance.entity_instance + :return: The newly created IfcDocumentReference entity + :rtype: ifcopenshell.entity_instance.entity_instance + + Example:: + + document = ifcopenshell.api.run("document.add_information", model) + ifcopenshell.api.run("document.edit_information", model, + information=document, + attributes={"Identification": "A-GA-6100", "Name": "Overall Plan", + "Location": "A-GA-6100 - Overall Plan.pdf"}) + + # In this case, we don't specify any more information, and so the + # reference is for the entire document, as opposed to a single page or + # chapter or section. + reference = ifcopenshell.api.run("document.add_reference", model, information=document) + + # Alternatively, we can specify a single section, such as by a + # subheading code. + reference2 = ifcopenshell.api.run("document.add_reference", model, information=document) + ifcopenshell.api.run("document.edit_reference", model, + reference=reference2, attributes={"Identification": "2.1.15"}) + """ self.file = file - self.settings = {"information": None} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"information": information} def execute(self): if self.file.schema == "IFC2X3": diff --git a/src/ifcopenshell-python/ifcopenshell/api/document/assign_document.py b/src/ifcopenshell-python/ifcopenshell/api/document/assign_document.py index c43c2afd3b..b62d62814b 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/document/assign_document.py +++ b/src/ifcopenshell-python/ifcopenshell/api/document/assign_document.py @@ -20,14 +20,45 @@ import ifcopenshell class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, product=None, document=None): + """Assigns a document to a product + + An object may be assigned to zero, one, or multiple documents. Almost + any object or property may be assigned to a document, though typically + we'd only use it for spaces, types, physical products and schedules. + Adding a new assignment is typically done using a document reference and + an object. IFC technically allows association with a document + information and an object, but this is not encouraged because it is not + consistent with other external relationships (such as classification + systems or libraries). + + :param product: The object to associate the document to. This could be + almost any sensible object in IFC. + :type product: ifcopenshell.entity_instance.entity_instance + :param document: The IfcDocumentReference to associate to, or + alternatively an IfcDocumentInformation, though this is not + recommended. + :type document: ifcopenshell.entity_instance.entity_instance + :return: The IfcRelAssociatesDocument relationship + :rtype: ifcopenshell.entity_instance.entity_instance + + Example:: + + document = ifcopenshell.api.run("document.add_information", model) + ifcopenshell.api.run("document.edit_information", model, + information=document, + attributes={"Identification": "A-GA-6100", "Name": "Overall Plan", + "Location": "A-GA-6100 - Overall Plan.pdf"}) + reference = ifcopenshell.api.run("document.add_reference", model, information=document) + + # Let's imagine storey represents an IfcBuildingStorey for the ground floor + ifcopenshell.api.run("document.assign_document", model, product=storey, document=reference) + """ self.file = file self.settings = { - "product": None, - "document": None, + "product": product, + "document": document, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): rel = self.get_document_rel() diff --git a/src/ifcopenshell-python/ifcopenshell/api/document/edit_information.py b/src/ifcopenshell-python/ifcopenshell/api/document/edit_information.py index 0eb65431c9..a511c41c93 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/document/edit_information.py +++ b/src/ifcopenshell-python/ifcopenshell/api/document/edit_information.py @@ -18,11 +18,29 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, information=None, attributes=None): + """Edits the attributes of an IfcDocumentInformation + + For more information about the attributes and data types of an + IfcDocumentInformation, consult the IFC documentation. + + :param reference: The IfcDocumentInformation entity you want to edit + :type reference: ifcopenshell.entity_instance.entity_instance + :param attributes: a dictionary of attribute names and values. + :type attributes: dict, optional + :return: None + :rtype: None + + Example:: + + document = ifcopenshell.api.run("document.add_information", model) + ifcopenshell.api.run("document.edit_information", model, + information=document, + attributes={"Identification": "A-GA-6100", "Name": "Overall Plan", + "Location": "A-GA-6100 - Overall Plan.pdf"}) + """ self.file = file - self.settings = {"information": None, "attributes": {}} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"information": information, "attributes": attributes or {}} def execute(self): for name, value in self.settings["attributes"].items(): diff --git a/src/ifcopenshell-python/ifcopenshell/api/document/edit_reference.py b/src/ifcopenshell-python/ifcopenshell/api/document/edit_reference.py index 342b1fbad2..8c855191a4 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/document/edit_reference.py +++ b/src/ifcopenshell-python/ifcopenshell/api/document/edit_reference.py @@ -18,11 +18,32 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, reference=None, attributes=None): + """Edits the attributes of an IfcDocumentReference + + For more information about the attributes and data types of an + IfcDocumentReference, consult the IFC documentation. + + :param reference: The IfcDocumentReference entity you want to edit + :type reference: ifcopenshell.entity_instance.entity_instance + :param attributes: a dictionary of attribute names and values. + :type attributes: dict, optional + :return: None + :rtype: None + + Example:: + + document = ifcopenshell.api.run("document.add_information", model) + ifcopenshell.api.run("document.edit_information", model, + information=document, + attributes={"Identification": "A-GA-6100", "Name": "Overall Plan", + "Location": "A-GA-6100 - Overall Plan.pdf"}) + reference = ifcopenshell.api.run("document.add_reference", model, information=document) + ifcopenshell.api.run("document.edit_reference", model, + reference=reference, attributes={"Identification": "2.1.15"}) + """ self.file = file - self.settings = {"reference": None, "attributes": {}} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"reference": reference, "attributes": attributes or {}} def execute(self): for name, value in self.settings["attributes"].items(): diff --git a/src/ifcopenshell-python/ifcopenshell/api/document/remove_information.py b/src/ifcopenshell-python/ifcopenshell/api/document/remove_information.py index 11a0fc6cd4..4cd18e051a 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/document/remove_information.py +++ b/src/ifcopenshell-python/ifcopenshell/api/document/remove_information.py @@ -21,11 +21,25 @@ import ifcopenshell.api class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, information=None): + """Removes a document information + + All references and associations are also removed. + + :param information: The IfcDocumentInformation to remove + :type information: ifcopenshell.entity_instance.entity_instance + :return: None + :rtype: None + + Example:: + + # Add a document + document = ifcopenshell.api.run("document.add_information", model) + # ... and remove it! + ifcopenshell.api.run("document.remove_information", model, information=document) + """ self.file = file - self.settings = {"information": None} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"information": information} def execute(self): for reference in self.settings["information"].HasDocumentReferences or []: diff --git a/src/ifcopenshell-python/ifcopenshell/api/document/remove_reference.py b/src/ifcopenshell-python/ifcopenshell/api/document/remove_reference.py index f4cc669912..3906cb4e00 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/document/remove_reference.py +++ b/src/ifcopenshell-python/ifcopenshell/api/document/remove_reference.py @@ -18,11 +18,24 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, reference=None): + """Remove a document reference + + All associations with objects are removed. + + :param reference: The IfcDocumentReference to remove + :type reference: ifcopenshell.entity_instance.entity_instance + :return: None + :rtype: None + + Example:: + + document = ifcopenshell.api.run("document.add_information", model) + reference = ifcopenshell.api.run("document.add_reference", model, information=document) + ifcopenshell.api.run("document.remove_reference", model, reference=reference) + """ self.file = file - self.settings = {"reference": None} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"reference": reference} def execute(self): for rel in self.settings["reference"].DocumentRefForObjects or []: diff --git a/src/ifcopenshell-python/ifcopenshell/api/document/unassign_document.py b/src/ifcopenshell-python/ifcopenshell/api/document/unassign_document.py index 8f66e76f77..802e7c0c33 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/document/unassign_document.py +++ b/src/ifcopenshell-python/ifcopenshell/api/document/unassign_document.py @@ -20,14 +20,38 @@ import ifcopenshell class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, product=None, document=None): + """Unassigns a document and a product association + + :param product: The object that the document reference or information is + related to. + :type product: ifcopenshell.entity_instance.entity_instance + :param document: The IfcDocumentReference (typically) or in rare cases + the IfcDocumentInformation that is associated with the product + :type document: ifcopenshell.entity_instance.entity_instance + :return: None + :rtype: None + + Example:: + + document = ifcopenshell.api.run("document.add_information", model) + ifcopenshell.api.run("document.edit_information", model, + information=document, + attributes={"Identification": "A-GA-6100", "Name": "Overall Plan", + "Location": "A-GA-6100 - Overall Plan.pdf"}) + reference = ifcopenshell.api.run("document.add_reference", model, information=document) + + # Let's imagine storey represents an IfcBuildingStorey for the ground floor + ifcopenshell.api.run("document.assign_document", model, product=storey, document=reference) + + # Now let's change our mind and remove the association + ifcopenshell.api.run("document.unassign_document", model, product=storey, document=reference) + """ self.file = file self.settings = { - "product": None, - "document": None, + "product": product, + "document": document, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): for rel in self.settings["product"].HasAssociations: