From aad4dad9a7689a745d40c18f8a3609cf3dc9e98b Mon Sep 17 00:00:00 2001 From: Dion Moult Date: Sun, 16 Feb 2025 07:46:22 +1100 Subject: [PATCH] Migrate documentation for IfcTester and make optional deps mandatory in PyPI I don't like this, but PyPI makes it really, really hard to "discover" optional deps and what they're used for. So it's just easier to make it a mandatory dependency and advanced users can always strip it out. This stops user reports about "it doesn't work out of the box I only did pip install ifctester" --- src/ifcopenshell-python/docs/ifctester.rst | 93 ++++++++++++++++++++++ src/ifctester/README.md | 62 +-------------- src/ifctester/pyproject.toml | 2 +- 3 files changed, 95 insertions(+), 62 deletions(-) diff --git a/src/ifcopenshell-python/docs/ifctester.rst b/src/ifcopenshell-python/docs/ifctester.rst index 0682bff803..56208dd198 100644 --- a/src/ifcopenshell-python/docs/ifctester.rst +++ b/src/ifcopenshell-python/docs/ifctester.rst @@ -11,3 +11,96 @@ PyPI .. code-block:: pip install ifctester + +Examples +-------- + +You can execute IfcTester using a CLI. + +.. code-block:: console + + # Validate an IFC with an IDS and report to console + python -m ifctester example.ids example.ifc + + # Generate a HTML report instead + python -m ifctester example.ids example.ifc -r Html -o report.html + +Alternatively, you can use Python: + +.. code-block:: python + + import ifcopenshell + from ifctester import ids, reporter + + # Create new IDS + specs = ids.Ids(title="My IDS") + + # add specification to it + spec = ids.Specification(name="My first specification") + spec.applicability.append(ids.Entity(name="IFCWALL")) + requirement = ids.Property( + baseName="IsExternal", + value="TRUE", + propertySet="Pset_WallCommon", + dataType="IfcBoolean", + uri="https://identifier.buildingsmart.org/uri/.../prop/LoadBearing", + instructions="Walls need to be load bearing.", + cardinality="required") + spec.requirements.append(requirement) + specs.specifications.append(spec) + + # Save to a file + specs.to_xml("IDS.xml") + + # Open IFC file: + my_ifc = ifcopenshell.open("model.ifc") + + # Validate IFC model against IDS requirements: + specs.validate(my_ifc) + + # Show results in a console + reporter.Console(specs).report() + + # Alternatively, to JSON + report = reporter.Json(specs) + report.report() + report.to_file("report.json") + + # Or to ODS spreadsheet + report = reporter.Ods(specs) + report.report() + report.to_file("report.ods") + + # Or to HTML spreadsheet + report = reporter.Html(specs) + report.report() + report.to_file("report.html") + + # Or to BCF + report = reporter.Bcf(specs) + report.report() + report.to_file("report.bcf") + +CLI manual +---------- + +.. code-block:: console + + $ python -m ifctester -h + + usage: __main__.py [-h] [-r REPORTER] [--no-color] [--excel-safe] [-o OUTPUT] ids [ifc] + + Uses an IDS to audit an IFC + + positional arguments: + ids Path to an IDS + ifc Path to an IFC + + options: + -h, --help show this help message and exit + -r REPORTER, --reporter REPORTER + The reporting method to view audit results + --no-color Disable colour output (supported by Console reporting) + --excel-safe Make sure exported ODS is safely exported for Excel + -o OUTPUT, --output OUTPUT + Output file (supported for all types of reporting except Console) diff --git a/src/ifctester/README.md b/src/ifctester/README.md index 98c82ec22f..d97685161d 100644 --- a/src/ifctester/README.md +++ b/src/ifctester/README.md @@ -1,63 +1,3 @@ # ifctester -With **IfcTester**, you can author and read **Information Delivery Specification** - **IDS** - files and validate your IFC models against IDS to see if your model is compliant. After the audit, you can generate reports in console, as a web page, JSON or BCF file. It works from the command line, as a web app, or as a library. - -## How to use it - -### Command line use - - -```bash -# run console reporter -python -m ifctester example.ids example.ifc -python -m ifctester example.ids example.ifc -r Html -o report.html -``` - -Available flags: - -- ``-r`` / ``--reporter``: The reporting method to view audit results. Availabe reporters: Console, Txt, Json, Html, Ods, Bcf -- ``--no-color``: Disable colour output (supported by Console reporting). -- ``--excel-safe``: Make sure exported ODS is safely exported for Excel. -- ``-o`` / ``--output``: Output file (supported for all types of reporting except Console). - -### Code example - -```python -import ifcopenshell -from ifctester import ids, reporter - - -# create new IDS -my_ids = ids.Ids(title="My IDS") - -# add specification to it -my_spec = ids.Specification(name="My first specification") -my_spec.applicability.append(ids.Entity(name="IFCWALL")) -property = ids.Property( - baseName="IsExternal", - value="TRUE", - propertySet="Pset_WallCommon", - dataType="IfcBoolean", - uri="https://identifier.buildingsmart.org/uri/.../prop/LoadBearing", - instructions="Walls need to be load bearing.", - cardinality="required") -my_spec.requirements.append(property) -my_ids.specifications.append(my_spec) - -# Save such IDS to file -result = my_ids.to_xml("SampleIDS.xml") - -# open IFC file: -my_ifc = ifcopenshell.open("MyIfcModel.ifc") - -# validate IFC model against IDS requirements: -my_ids.validate(my_ifc) - -# show results: -reporter.Console(my_ids).report() -``` - - -### ifctester web app - -Can be started by `cd webapp && python app.py`. +Experimental webapp can be started by `cd webapp && python app.py`. diff --git a/src/ifctester/pyproject.toml b/src/ifctester/pyproject.toml index 04f67b5770..16ca9b1333 100644 --- a/src/ifctester/pyproject.toml +++ b/src/ifctester/pyproject.toml @@ -15,7 +15,7 @@ classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)", ] -dependencies = ["ifcopenshell", "python-dateutil", "xmlschema", "numpy"] +dependencies = ["ifcopenshell", "python-dateutil", "xmlschema", "numpy", "odfpy", "pystache", "bcf-client"] [project.urls] Homepage = "http://ifcopenshell.org"