diff --git a/src/ifcopenshell-python/docs/bsdd.rst b/src/ifcopenshell-python/docs/bsdd.rst index 568c685983..2f20e5e95d 100644 --- a/src/ifcopenshell-python/docs/bsdd.rst +++ b/src/ifcopenshell-python/docs/bsdd.rst @@ -43,6 +43,7 @@ Examples Learning how to use the bSDD is best done by reading the official Swagger API docs. .. code-block:: python + from bsdd import Client,apply_ifc_classification_properties from pprint import pprint diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python.rst b/src/ifcopenshell-python/docs/ifcopenshell-python.rst index 9eebe129d4..bbe503c64b 100644 --- a/src/ifcopenshell-python/docs/ifcopenshell-python.rst +++ b/src/ifcopenshell-python/docs/ifcopenshell-python.rst @@ -17,4 +17,5 @@ capabilities of the C++ core are available in Python. ifcopenshell-python/geometry_creation ifcopenshell-python/geometry_tree ifcopenshell-python/selector_syntax - ifcopenshell-python/developer_guide + ifcopenshell-python/schema_querying + ifcopenshell-python/validation diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python/developer_guide.rst b/src/ifcopenshell-python/docs/ifcopenshell-python/developer_guide.rst deleted file mode 100644 index d664cbe111..0000000000 --- a/src/ifcopenshell-python/docs/ifcopenshell-python/developer_guide.rst +++ /dev/null @@ -1,15 +0,0 @@ -Developer Guide -=============== - -The core module implements low-level functionality to read and write IFC data. This includes: - -- Reading IFC data from different serialisations into Python objects -- Accessing direct and indirect attributes of IFC entities -- Creating IFC entities -- Generating GlobalIds -- Removing IFC entities and all references -- Modifying IFC direct attributes -- Checking IFC class inheritance -- Validating IFC data - -TODO diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python/schema_querying.rst b/src/ifcopenshell-python/docs/ifcopenshell-python/schema_querying.rst new file mode 100644 index 0000000000..1cd6fbd1a8 --- /dev/null +++ b/src/ifcopenshell-python/docs/ifcopenshell-python/schema_querying.rst @@ -0,0 +1,73 @@ +Schema querying +=============== + +Schema declarations +------------------- + +IfcOpenShell can query the IFC schema itself without instantiating or loading an IFC dataset. + +.. code-block:: python + + import ifcopenshell + ifc4 = ifcopenshell.schema_by_name("IFC4") + +A schema definition is known as a declaration. You may loop through all declarations or retrieve a declaration by name. All declarations have a name. + +.. code-block:: python + + for declaration in ifc4.declarations(): + print(declaration.name()) # 'IfcAbsorbedDoseMeasure', 'IfcAccelerationMeasure', 'IfcActionRequest', ... + + ifcwall = ifc4.declaration_by_name("IfcWall") + +You can check if an entity is abstract, and retrive both the supertype and subtypes of an entity: + +.. code-block:: python + + print(ifcwall.is_abstract()) # False + print(ifcwall.supertype()) # + print(ifcwall.subtypes()) # (, ) + +You can retrieve only the direct attributes of an entity, or all the direct attributes including inherited attributes, or inverse attributes: + +.. code-block:: python + + print(ifcwall.attributes()) + print(ifcwall.all_attributes()) + print(ifcwall.all_inverse_attributes()) + +buildingSMART property set templates +------------------------------------ + +For each IFC schema version, buildingSMART publishes built in property and quantity set templates for standardised properties. These define property names, property sets, data types, and which IFC class they are applicable to. You can query these templates. + +.. code-block:: python + + import ifcopenshell.util.pset + templates = ifcopenshell.util.pset.PsetQto("IFC4") + +To get just the names of applicable templates for an entity: + +.. code-block:: python + + # ['Pset_EnvironmentalImpactIndicators', 'Pset_EnvironmentalImpactValues', 'Pset_WallCommon', 'Qto_WallBaseQuantities', ...] + print(templates.get_applicable_names("IfcWall")) + +They may also be retrieved as an ``IfcPropertySetTemplate`` entity: + +.. code-block:: python + + print(templates.get_applicable("IfcWall")) + +A single template may be retrieved by name: + +.. code-block:: python + + templates.get_by_name('Pset_WallCommon') + +You may add your own IFC files containing pset template definitions: + +.. code-block:: python + + my_pset_library = ifcopenshell.open('/path/to/library.ifc') + templates.templates.append(my_pset_library) diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python/validation.rst b/src/ifcopenshell-python/docs/ifcopenshell-python/validation.rst new file mode 100644 index 0000000000..3a0847d80a --- /dev/null +++ b/src/ifcopenshell-python/docs/ifcopenshell-python/validation.rst @@ -0,0 +1,78 @@ +Validation +========== + +SPF syntax validation +--------------------- + +IfcOpenShell can validate whether or not an IFC-SPF file contains correct SPF syntax. + +.. code-block:: + + $ python -m ifcopenshell.simple_spf path/to/model.ifc + Valid + +Here are some examples of failures: + +.. code-block:: + + $ python -m ifcopenshell.simple_spf fixtures/fail_double_comma.ifc + On line 8 column 21: + Unexpected comma (',') + Expecting one of DBLQUOTE DOT HASH INT LPAR NONE QUOTE REAL STAR UPPER + 00008 | #1=IFCPERSON($,$,'',,$,$,$,$); + ^ + + $ python -m ifcopenshell.simple_spf fixtures/fail_double_semi.ifc + On line 27 column 66: + Unexpected semicolon (';') + Expecting one of ENDSEC HASH + 00027 | #20=IFCPROJECT('2AyG2X0sb16Bjd4gQc07yZ',#5,'',$,$,$,$,(#11),#19);; + ^ + + $ python -m ifcopenshell.simple_spf fixtures/fail_duplicate_id.ifc + On line 27: + Duplicate instance name #19 + 00027 | #19=IFCPROJECT('2AyG2X0sb16Bjd4gQc07yZ',#5,'',$,$,$,$,(#11),#19); + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + $ python -m ifcopenshell.simple_spf fixtures/fail_no_header.ifc + On line 2 column 1: + Unexpected hex ('F') + Expecting HEADER + 00002 | FILE_DESCRIPTION(('ViewDefinition [CoordinationView]'),'2;1'); + ^ + +The optional ``--json`` argument may be used to instead get results in JSON. + +.. code-block:: + + $ python -m ifcopenshell.simple_spf test.ifc + {"type": "unexpected_token", "lineno": 8, "column": 48, "found_type": "semicolon", "found_value": ";", "expected": ["ENDSEC"], "line": "#1= IFCPERSON($,'Nicht definiert',$,$,$,$,$,$);;", "message": "On line 8 column 48:\nUnexpected semicolon (';')\nExpecting ENDSEC\n00008 | #1= IFCPERSON($,'Nicht definiert',$,$,$,$,$,$);;\n ^"} + +IFC schema validation +--------------------- + +IfcOpenShell can validate models against the IFC schema itself. It checks against attributes, entity names, data types, cardinality, and where rules. + +.. code-block:: console + + $ python -m ifcopenshell.validate -h + + usage: validate.py [-h] [--rules] [--json] [--fields] [--spf] files [files ...] + + positional arguments: + files The IFC file to validate. + + options: + -h, --help show this help message and exit + --rules Run express rules. + --json Output in JSON format. + --fields Output more detailed information about failed entities (only with --json). + --spf Output entities in SPF format (only with --json). + + +For example: + +.. code-block:: bash + + python -m ifcopenshell.validate /path/to/model.ifc --rules