Metadata-Version: 2.4
Name: ifc2data
Version: 1.1.0
Summary: Python client for the Ifc2Data API
Author: Yohann Schatz
License: MIT
Project-URL: Homepage, https://www.ifc2data.com/
Project-URL: Repository, https://github.com/y-schatz/ifc2data
Project-URL: Issues, https://github.com/y-schatz/ifc2data/issues
Keywords: IFC,BIM,IfcOpenShell,construction,building,engineering,data,API
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# Ifc2Data Python Client

A Python client for the **Ifc2Data** API 
https://www.ifc2data.com/

Ifc2Data allows you to upload IFC files and export structured datasets in multiple formats such as XLSX, CSV, SQL, JSON, and more.

This package provides both:

- A synchronous client (`Client`)
- An asynchronous client (`AsyncClient`)

for seamless integration into Python applications, automation workflows, and backend services.

---

## Features

- Synchronous and asynchronous support
- Multiple output formats supported
- Built-in parameter validation
- Automatic retry mechanism for network reliability
- Lightweight and easy to integrate

---

## Installation

```bash
pip install ifc2data
```

---

## Prerequisites

Before using this package :
1.  Create an account on Ifc2Data : https://www.ifc2data.com/signup/
2.  Request an API key : yohann.schatz@hesge.ch

---

## Quick Start

### Synchronous Client

```python
from ifc2data import Client

api_key = "YOUR_API_KEY"

file_path = r"C:\path\to\your\file\File.ifc"

output_format = "xlsx"

parameters = {
    "elements": ["IfcWall"],
    "properties": ["IsExternal", "LoadBearing"],
    "quantities": []
}

client = Client(api_key)

result = client.run(
    file_path=file_path,
    output_format=output_format,
    parameters=parameters
)

if result.done:
    output_path = client.download(
        result,
        r"C:\path\to\your\file"
    )

    print("Saved to:", output_path)
```

### Asynchronous Client

```python
import asyncio
from ifc2data import AsyncClient

api_key = "YOUR_API_KEY"

file_path = r"C:\path\to\your\file\File.ifc"

output_format = "xlsx"

parameters = {
    "elements": ["IfcWall"],
    "properties": ["IsExternal", "LoadBearing"],
    "quantities": []
}

async def main():

    client = AsyncClient(api_key)

    result = await client.run(
        file_path=file_path,
        output_format=output_format,
        parameters=parameters
    )

    if result.done:

        output_path = await client.download(
            result,
            r"C:\path\to\your\file"
        )

        print("Saved to:", output_path)

asyncio.run(main())
```

---

## How it works

1. Upload an IFC model
2. Configure extraction parameters
3. Execute the processing pipeline
4. Receive a structured API response
5. Download the generated output file

---

## Response

### Response Object

The `run()` method returns a `PipelineResponse` object.

```python
print(result.status)
print(result.message)

if result.data:
    print(result.data.id)
    print(result.data.file_name)
```

### Response Structure

| Attribute | Type           | Description                            |
| --------- | -------------- | -------------------------------------- |
| `status`  | `str`          | Pipeline execution status              |
| `message` | `str`          | Human-readable API message             |
| `data`    | `PipelineData` | Processed file information             |
| `done`    | `bool`         | Returns `True` if processing succeeded |

---

## Output Formats

| Format         | Key          |
| -------------- | ------------ |
| BSON (MongoDB) | `bson`       |
| CSV            | `csv`        |
| JSON           | `json`       |
| RDF            | `rdf`        |
| SQL            | `sql`        |
| SQL (3NF)      | `sql_3nf`    |
| SQLite         | `sqlite`     |
| SQLite (3NF)   | `sqlite_3nf` |
| Excel (XLSX)   | `xlsx`       |

---

## Parameters

The `parameters` dictionary controls how IFC data is filtered and exported.

### Available Parameters

| Key               | Required | Type        | Empty Allowed | Description            |
| ----------------- | -------- | ----------- | ------------- | ---------------------- |
| `elements`        | Yes      | `List[str]` | No            | IFC classes to extract |
| `classifications` | No       | `List[str]` | Yes           | Classification filters |
| `documents`       | No       | `List[str]` | Yes           | Document filters       |
| `materials`       | No       | `List[str]` | Yes           | Material filters       |
| `properties`      | No       | `List[str]` | Yes           | Property filters       |
| `quantities`      | No       | `List[str]` | Yes           | Quantity filters       |

### Parameter Examples

#### Minimal Example

```python
parameters = {
    "elements": ["IfcWall"]
}
```

#### Multiple IFC Elements

```python
parameters = {
    "elements": [
        "IfcWall",
        "IfcDoor",
        "IfcWindow"
    ]
}
```

#### Property Filtering

```python
parameters = {
    "elements": ["IfcWall"],
    "properties": [
        "FireRating",
        "LoadBearing",
        "IsExternal"
    ]
}
```

#### Material Filtering

```python
parameters = {
    "elements": ["IfcSlab"],
    "materials": [
        "Concrete",
        "Steel"
    ]
}
```

#### Quantity Extraction

```python
parameters = {
    "elements": ["IfcBeam"],
    "quantities": [
        "Length",
        "Area",
        "Volume"
    ]
}
```

#### No Filter Example

```python
parameters = {
    "elements": ["IfcWall"],
    "properties": []
}
```

---

## Validation Rules

The SDK validates parameters before sending requests to the API.

Validation includes:

- Required parameter checks
- Output format validation
- IFC class validation
- Parameter type validation
- Unknown parameter detection

Invalid configurations raise a `ValueError`.

---

## Error Handling

```python
try:

    result = client.run(
        file_path,
        output_format,
        parameters
    )

except ValueError as e:
    print("Validation error:", e)

except Exception as e:
    print("Request failed:", e)
```

---

## Verbose Mode

Enable verbose mode to inspect API requests and responses.

```python
result = client.run(
    file_path=file_path,
    output_format="xlsx",
    parameters=parameters,
    verbose=True
)
```
Verbose mode displays:

- Request URL
- Output format
- Parameters
- HTTP response status
- API response payload

---

## Notes

- IFC files must be valid and readable
- Network retries are automatically handled internally
- Empty filter lists are normalized automatically
- Downloaded files are streamed to disk to reduce memory usage

---

## License

This project is licensed under the MIT License.

---

## Author

Yohann Schatz
