Rename ifcapi to ifcedit, README and black

2026-09-11 06:18:09 +00:00 · 2026-02-09 22:59:11 +00:00
parent 12ed2d1ec3
commit b1f1de954d
16 changed files with 528 additions and 78 deletions
@@ -0,0 +1,208 @@
+# ifcedit
+
+A CLI wrapper that exposes all 350+ `ifcopenshell.api` mutation functions as
+shell commands. Functions are auto-discovered at runtime via introspection --
+no hardcoded list to maintain.
+
+## Installation
+
+```bash
+pip install ifcedit
+```
+
+Requires `ifcopenshell`.
+
+## Usage
+
+```
+ifcedit <command> [options] [--format json|text]
+```
+
+Three subcommands: `list` to discover functions, `docs` to read their
+documentation, and `run` to execute them.
+
+## Subcommands
+
+### list
+
+Discover available API modules and their functions.
+
+**List all modules:**
+
+```bash
+ifcedit list
+```
+
+```json
+[
+  {
+    "module": "root",
+    "description": "Functions for creating project-level entities",
+    "functions": ["create_entity", "remove_product", "copy_class"],
+    "count": 3
+  },
+  {
+    "module": "spatial",
+    "description": "Functions for managing spatial relationships",
+    "functions": ["assign_container", "unassign_container"],
+    "count": 2
+  }
+]
+```
+
+**List functions in a module:**
+
+```bash
+ifcedit list root
+```
+
+```json
+[
+  {
+    "name": "create_entity",
+    "description": "Create an IFC entity with optional initial attributes",
+    "params": [
+      {"name": "ifc_class", "type": "str", "required": true},
+      {"name": "name", "type": "Optional[str]"}
+    ]
+  }
+]
+```
+
+### docs
+
+Show full documentation for a specific function, including parameter
+descriptions from docstrings and return type.
+
+```bash
+ifcedit docs root.create_entity
+```
+
+```json
+{
+  "module": "root",
+  "function": "create_entity",
+  "description": "Create an IFC entity with optional initial attributes",
+  "long_description": "This function creates a new entity instance...",
+  "params": [
+    {
+      "name": "ifc_class",
+      "type": "str",
+      "required": true,
+      "description": "The IFC class name (e.g. 'IfcWall', 'IfcProject')"
+    },
+    {
+      "name": "name",
+      "type": "Optional[str]",
+      "description": "Optional name attribute"
+    }
+  ],
+  "return_type": "ifcopenshell.entity_instance",
+  "return_description": "The newly created entity instance"
+}
+```
+
+### run
+
+Execute an API function against an IFC file. Parameters are passed as
+`--key value` pairs after the function name.
+
+```bash
+ifcedit run model.ifc root.create_entity --ifc_class IfcWall --name "My Wall"
+```
+
+```json
+{
+  "ok": true,
+  "result": {"id": 42, "type": "IfcWall", "name": "My Wall"}
+}
+```
+
+**Options:**
+
+- `-o, --output <path>` -- write to a different file instead of overwriting the input
+- `--dry-run` -- validate parameters without executing or saving
+
+```bash
+# Save to a new file
+ifcedit run model.ifc root.create_entity -o out.ifc --ifc_class IfcWall
+
+# Validate without executing
+ifcedit run model.ifc root.create_entity --dry-run --ifc_class IfcWall
+```
+
+Dry-run output shows the resolved parameters:
+
+```json
+{
+  "ok": true,
+  "dry_run": true,
+  "module": "root",
+  "function": "create_entity",
+  "args": {"ifc_class": "IfcWall", "name": "My Wall"}
+}
+```
+
+## Parameter type coercion
+
+CLI strings are automatically converted to the types expected by each API
+function, using the function's type annotations:
+
+| Type | CLI input | Python value |
+|------|-----------|--------------|
+| `str` | `"hello"` | `"hello"` |
+| `int` | `"42"` or `"#42"` | `42` |
+| `float` | `"3.14"` | `3.14` |
+| `bool` | `"true"`, `"1"`, `"yes"` | `True` |
+| `Optional[X]` | `"none"` | `None` |
+| `entity_instance` | `"42"` or `"#42"` | resolved from model by step ID |
+| `list[entity_instance]` | `"5,6,7"` or `"[5, 6, 7]"` | list of resolved entities |
+| `dict` | `'{"key": "val"}'` | parsed JSON object |
+| `Literal["A", "B"]` | `"A"` | validated against allowed values |
+
+## Examples
+
+```bash
+# Create a project
+ifcedit run model.ifc root.create_entity --ifc_class IfcProject --name "My Project"
+
+# Assign an element to a storey
+ifcedit run model.ifc spatial.assign_container --products 10 --relating_structure 4
+
+# Assign multiple elements at once
+ifcedit run model.ifc aggregate.assign_object --products "5,6,7" --relating_object 1
+
+# Add a property set
+ifcedit run model.ifc pset.add_pset --product 10 --name "Pset_WallCommon"
+
+# Edit properties
+ifcedit run model.ifc pset.edit_pset --pset 15 \
+    --properties '{"IsExternal": true, "FireRating": "2HR"}'
+```
+
+## Error handling
+
+Errors are reported in the JSON response:
+
+```json
+{
+  "ok": false,
+  "error": "Entity #999 not found in model"
+}
+```
+
+Exit code is 0 on success, 1 on error.
+
+## Relationship to ifcquery
+
+`ifcedit` and `ifcquery` are complementary tools:
+
+- **ifcquery** reads and inspects IFC models (summary, tree, info, select, relations, clash)
+- **ifcedit** modifies IFC models by wrapping `ifcopenshell.api` functions
+
+A typical workflow: inspect with `ifcquery`, look up the right API function
+with `ifcedit docs`, then apply changes with `ifcedit run`.
+
+## License
+
+LGPLv3+ -- see the IfcOpenShell project license.