python-materialsdb 0.1.0__tar.gz → 0.2.0__tar.gz

python_materialsdb-0.2.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: python-materialsdb
+Version: 0.2.0
+Summary: A library to work with materialsdb.org open standard for building materials.
+Author-email: Cyril Waechter <cyrwae@hotmail.com>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/CyrilWaechter/python-materialsdb
+Project-URL: Bug Tracker, https://github.com/CyrilWaechter/python-materialsdb/issues
+Project-URL: Community, https://community.osarch.org/
+Keywords: materials,BIM,ifcopenshell,IFC
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: lxml
+Provides-Extra: ifc
+Requires-Dist: ifcopenshell; extra == "ifc"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-benchmark; extra == "dev"
+Requires-Dist: ruff==0.16.4; extra == "dev"
+Requires-Dist: ty==0.0.74; extra == "dev"
+Dynamic: license-file
+
+python-materialsdb is an unofficial python library for [materialsdb.org][1] an open format and database for building materials.
+
+# Features :
+## Package
+* serialiser.py :
+    * from xml : deserialise from materialsdb*.xsd compliant xml file
+    * to xml : serealise classes to a materialsdb*.xsd compliant xml file
+* classes.py : generated classes corresponding to XML elements
+* cache.py : cache latest materials data from producers
+* config.py : set and get user config as language and country
+* ifc/project_library.py : convert deserialised source into IFC (IfcProjectLibrary)
+* gui/server.py : stdlib-only web application to browse and export cached materials (materialsdb-gui)
+
+## devutils
+* classes_generator.py : generate classes (dataclasses except for simple type) for materialsdb*.xsd elements
+
+# config
+Materials data are often localized. You can set your language and country this way:
+```python
+from materialsdb import config
+
+config.set_lang("fr")
+config.set_country("CH")
+```
+Note: in materialsdb standard languages are [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) codes and countries are [ISO_3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) codes.
+
+# Usage examples :
+Check out some [examples](examples):
+* [Convert latest materials data to ifc](examples/generate_ifc_project_libraries.py)
+* [Create your own materialsdb.org compliant XML](examples/create_layers.py)
+
+# Querying materials :
+The library keeps an sqlite index of the cached materials data for fast
+filtering and single-material access:
+
+```python
+from materialsdb import query
+
+query.refresh()                                   # incremental update from cached xml
+rows = query.search("isolant", sort="lambda")     # filtered, sorted summaries
+material = query.get_material(rows[0].id)         # full material dataclass
+```
+
+# Create a single material in IFC :
+Append one material into an existing ifcopenshell file (idempotent), or build a minimal standalone file.
+
+```python
+from materialsdb import query
+from materialsdb.ifc.material_builder import add_material, create_material_file
+
+material = query.get_material("<materialsdb-id>")
+
+add_material(existing_ifc_file, material, company="Producer")   # idempotent append
+file = create_material_file("<materialsdb-id>")                 # standalone .ifc
+file.write("single_material.ifc")
+```
+
+# Material picker GUI :
+Launch the local web application (stdlib only, no extra dependencies):
+
+```bash
+materialsdb-gui            # opens http://127.0.0.1:8619 in your browser
+```
+
+Or run straight from a source checkout without installing:
+
+```bash
+PYTHONPATH=src python3 -m materialsdb.gui
+```
+
+The materials index uses schema v2: the first launch after upgrading rebuilds
+it automatically (previous index is discarded — source of truth is your cached
+XML). Click *refresh cache* once to repopulate.
+
+Browse, sort and filter all cached materials; multi-select then either export
+a standalone `.ifc`, or open one of your own `.ifc` files and append the
+selected materials into it. The same HTTP API powers future BIM software
+plugins (all mutating calls require a per-launch token).
+
+# Construction maker :
+Compose thermal constructions from materialsdb materials and compute their
+U-value (ISO 6946 / SIA 180 surface resistance presets):
+
+```bash
+PYTHONPATH=src python3 -m materialsdb.gui   # then open constructions.html
+```
+
+Create a construction, add materials from the catalog, adjust layer
+thicknesses in millimetres and read the resulting U-value live. Save
+constructions as JSON in your cache directory, export them as standalone
+`.ifc` files containing an `IfcMaterialLayerSet`, or append them into an
+already-open session file.
+
+You can also push the construction straight into the IFC model open in
+Bonsai (same target picker as the materials page): it is created or updated
+as an `IfcWallType`/`IfcSlabType`/`IfcRoofType` (per the design usage,
+generic creating all three) with its `IfcMaterialLayerSet` — undoable with
+Ctrl+Z.
+
+# Bonsai integration :
+Push materials straight from the picker into the IFC model open in
+[Bonsai](https://bonsai.ifcopenshell.org). Install it from the
+extension repository: in Blender, *Preferences ▸ Get Extensions ▸ ⌄ ▸
+Add Remote Repository* and add
+`https://cyrilwaechter.github.io/python-materialsdb/`, then install
+*materialsdb listener* (updates appear in the same panel). Manual
+install stays available: build `dist/materialsdb_listener.zip` with
+`python3 dev_utils/build_bonsai_addon.py` and use
+*Extensions ▸ Install from Disk*. Start the listener from the
+materialsdb panel in the 3D-view sidebar. The panel can also start the
+GUI server itself (*Start server & open picker*) — it needs
+`pip install python-materialsdb` in a system Python (set the
+interpreter in the add-on preferences if autodiscovery picks the wrong
+one). Then run `materialsdb-gui` as
+usual and hit *send to:* (picking the target instance) in the picker or
+the construction maker. Materials are registered
+into the model's material library (identity + per-layer psets included);
+assigning them to objects stays a normal Bonsai action. Pushed
+constructions become typed elements (`IfcWallType`/`IfcSlabType`/
+`IfcRoofType` per the design usage) with their `IfcMaterialLayerSet`,
+visible in the outliner and revertible with Ctrl+Z. Round-trip: select
+the wall (or its type) in Bonsai and hit *Send type to composer* in the
+materialsdb panel — the construction appears under *incoming from model*
+on the constructions page for editing. Layers whose material is not a
+materialsdb material are kept as "model material" placeholders (λ read
+from the model) and re-attach to the same material on push-back.
+
+# How to install
+## Using pip
+```bash
+pip install python-materialsdb
+```
+
+# Dependencies
+* [lxml][2] (BSD) : xml parser (tested with version 6.1.1)
+* [ifcopenshell][3] (LGPL) : ifc read/write (tested with version 0.8.5)
+
+# Third parties :
+* [materialsdb.org][1] (GPL) : materials schema
+
+[1]: http://www.materialsdb.org
+[2]: https://lxml.de
+[3]: ifcopenshell.org

python_materialsdb-0.2.0/README.md

@@ -0,0 +1,143 @@
+python-materialsdb is an unofficial python library for [materialsdb.org][1] an open format and database for building materials.
+
+# Features :
+## Package
+* serialiser.py :
+    * from xml : deserialise from materialsdb*.xsd compliant xml file
+    * to xml : serealise classes to a materialsdb*.xsd compliant xml file
+* classes.py : generated classes corresponding to XML elements
+* cache.py : cache latest materials data from producers
+* config.py : set and get user config as language and country
+* ifc/project_library.py : convert deserialised source into IFC (IfcProjectLibrary)
+* gui/server.py : stdlib-only web application to browse and export cached materials (materialsdb-gui)
+
+## devutils
+* classes_generator.py : generate classes (dataclasses except for simple type) for materialsdb*.xsd elements
+
+# config
+Materials data are often localized. You can set your language and country this way:
+```python
+from materialsdb import config
+
+config.set_lang("fr")
+config.set_country("CH")
+```
+Note: in materialsdb standard languages are [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) codes and countries are [ISO_3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) codes.
+
+# Usage examples :
+Check out some [examples](examples):
+* [Convert latest materials data to ifc](examples/generate_ifc_project_libraries.py)
+* [Create your own materialsdb.org compliant XML](examples/create_layers.py)
+
+# Querying materials :
+The library keeps an sqlite index of the cached materials data for fast
+filtering and single-material access:
+
+```python
+from materialsdb import query
+
+query.refresh()                                   # incremental update from cached xml
+rows = query.search("isolant", sort="lambda")     # filtered, sorted summaries
+material = query.get_material(rows[0].id)         # full material dataclass
+```
+
+# Create a single material in IFC :
+Append one material into an existing ifcopenshell file (idempotent), or build a minimal standalone file.
+
+```python
+from materialsdb import query
+from materialsdb.ifc.material_builder import add_material, create_material_file
+
+material = query.get_material("<materialsdb-id>")
+
+add_material(existing_ifc_file, material, company="Producer")   # idempotent append
+file = create_material_file("<materialsdb-id>")                 # standalone .ifc
+file.write("single_material.ifc")
+```
+
+# Material picker GUI :
+Launch the local web application (stdlib only, no extra dependencies):
+
+```bash
+materialsdb-gui            # opens http://127.0.0.1:8619 in your browser
+```
+
+Or run straight from a source checkout without installing:
+
+```bash
+PYTHONPATH=src python3 -m materialsdb.gui
+```
+
+The materials index uses schema v2: the first launch after upgrading rebuilds
+it automatically (previous index is discarded — source of truth is your cached
+XML). Click *refresh cache* once to repopulate.
+
+Browse, sort and filter all cached materials; multi-select then either export
+a standalone `.ifc`, or open one of your own `.ifc` files and append the
+selected materials into it. The same HTTP API powers future BIM software
+plugins (all mutating calls require a per-launch token).
+
+# Construction maker :
+Compose thermal constructions from materialsdb materials and compute their
+U-value (ISO 6946 / SIA 180 surface resistance presets):
+
+```bash
+PYTHONPATH=src python3 -m materialsdb.gui   # then open constructions.html
+```
+
+Create a construction, add materials from the catalog, adjust layer
+thicknesses in millimetres and read the resulting U-value live. Save
+constructions as JSON in your cache directory, export them as standalone
+`.ifc` files containing an `IfcMaterialLayerSet`, or append them into an
+already-open session file.
+
+You can also push the construction straight into the IFC model open in
+Bonsai (same target picker as the materials page): it is created or updated
+as an `IfcWallType`/`IfcSlabType`/`IfcRoofType` (per the design usage,
+generic creating all three) with its `IfcMaterialLayerSet` — undoable with
+Ctrl+Z.
+
+# Bonsai integration :
+Push materials straight from the picker into the IFC model open in
+[Bonsai](https://bonsai.ifcopenshell.org). Install it from the
+extension repository: in Blender, *Preferences ▸ Get Extensions ▸ ⌄ ▸
+Add Remote Repository* and add
+`https://cyrilwaechter.github.io/python-materialsdb/`, then install
+*materialsdb listener* (updates appear in the same panel). Manual
+install stays available: build `dist/materialsdb_listener.zip` with
+`python3 dev_utils/build_bonsai_addon.py` and use
+*Extensions ▸ Install from Disk*. Start the listener from the
+materialsdb panel in the 3D-view sidebar. The panel can also start the
+GUI server itself (*Start server & open picker*) — it needs
+`pip install python-materialsdb` in a system Python (set the
+interpreter in the add-on preferences if autodiscovery picks the wrong
+one). Then run `materialsdb-gui` as
+usual and hit *send to:* (picking the target instance) in the picker or
+the construction maker. Materials are registered
+into the model's material library (identity + per-layer psets included);
+assigning them to objects stays a normal Bonsai action. Pushed
+constructions become typed elements (`IfcWallType`/`IfcSlabType`/
+`IfcRoofType` per the design usage) with their `IfcMaterialLayerSet`,
+visible in the outliner and revertible with Ctrl+Z. Round-trip: select
+the wall (or its type) in Bonsai and hit *Send type to composer* in the
+materialsdb panel — the construction appears under *incoming from model*
+on the constructions page for editing. Layers whose material is not a
+materialsdb material are kept as "model material" placeholders (λ read
+from the model) and re-attach to the same material on push-back.
+
+# How to install
+## Using pip
+```bash
+pip install python-materialsdb
+```
+
+# Dependencies
+* [lxml][2] (BSD) : xml parser (tested with version 6.1.1)
+* [ifcopenshell][3] (LGPL) : ifc read/write (tested with version 0.8.5)
+
+# Third parties :
+* [materialsdb.org][1] (GPL) : materials schema
+
+[1]: http://www.materialsdb.org
+[2]: https://lxml.de
+[3]: ifcopenshell.org

python_materialsdb-0.2.0/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-materialsdb"
+version = "0.2.0"
+description = "A library to work with materialsdb.org open standard for building materials."
+readme = "README.md"
+license = "GPL-3.0-or-later"
+authors = [{ name = "Cyril Waechter", email = "cyrwae@hotmail.com" }]
+keywords = ["materials", "BIM", "ifcopenshell", "IFC"]
+dependencies = ["lxml"]
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.urls]
+Homepage = "https://github.com/CyrilWaechter/python-materialsdb"
+"Bug Tracker" = "https://github.com/CyrilWaechter/python-materialsdb/issues"
+Community = "https://community.osarch.org/"
+
+[project.scripts]
+materialsdb-gui = "materialsdb.gui.__main__:main"
+
+[project.optional-dependencies]
+ifc = ["ifcopenshell"]
+dev = [
+    "pytest",
+    "pytest-benchmark",
+    "ruff==0.16.4",
+    "ty==0.0.74",
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["*.json", "*.xsd", "*.html", "*.js"]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+markers = [
+    "benchmark: performance benchmarks (deselected by default)",
+]
+addopts = "-m 'not benchmark'"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+extend-exclude = [
+    "src/materialsdb/classes.py",
+    "*.md",
+]
+
+[tool.ty.src]
+include = ["src", "tests", "dev_utils", "examples"]
+
+[[tool.ty.overrides]]
+# Generated file: excluded from ruff/ty per Global Constraints (no-drift policy).
+include = ["src/materialsdb/classes.py"]
+[tool.ty.overrides.rules]
+all = "ignore"
+
+[tool.ty.analysis]
+# lxml ships no type information; treat as Any instead of erroring on every use.
+replace-imports-with-any = ["lxml.**"]
+
+[[tool.ty.overrides]]
+# Generator emits dynamic setattr-based classes; ty cannot follow the flow of
+# self.file (assigned inside parse_schema) nor os.startfile (Windows-only).
+include = ["dev_utils/classes_generator.py", "examples/generate_ifc_project_libraries.py"]
+[tool.ty.overrides.rules]
+unresolved-attribute = "ignore"
+
+[[tool.ty.overrides]]
+# Examples exercise the generated model whose Optional list fields are
+# populated before use; runtime-valid, inference-hostile.
+include = ["examples/create_layers.py"]
+[tool.ty.overrides.rules]
+unresolved-attribute = "ignore"
+possibly-missing-attribute = "ignore"
+
+[[tool.ty.overrides]]
+# ifcopenshell's own annotations disagree with its runtime API here.
+include = ["src/materialsdb/ifc/project_library.py"]
+[tool.ty.overrides.rules]
+invalid-argument-type = "ignore"
+invalid-assignment = "ignore"

python_materialsdb-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

python_materialsdb-0.2.0/src/materialsdb/__init__.py

@@ -0,0 +1,3 @@
+from materialsdb import cache, classes, config, ifc, serialiser
+
+__all__ = ["cache", "classes", "config", "ifc", "serialiser"]

{python_materialsdb-0.1.0 → python_materialsdb-0.2.0}/src/materialsdb/cache.py

@@ -2,7 +2,7 @@ import os
 import pathlib
 import urllib.request
 from collections import namedtuple
-from typing import Optional
+
 from lxml import etree
 
 MATERIALSDBINDEXURLLIST = [
@@ -13,9 +13,7 @@ MATERIALSDBINDEXURLLIST = [
 
 def get_cache_folder():
     cache_dir = pathlib.Path(
-        os.environ.get("APPDATA")
-        or os.environ.get("XDG_CACHE_HOME")
-        or pathlib.Path.home() / ".cache"
+        os.environ.get("APPDATA") or os.environ.get("XDG_CACHE_HOME") or pathlib.Path.home() / ".cache"
     ).joinpath(
         "materialsdb",
     )
@@ -35,7 +33,7 @@ def parse_cached_index(index) -> etree._ElementTree:
     return etree.ElementTree(root)
 
 
-def get_by_id(root: etree._Element, id: str) -> Optional[etree._Element]:
+def get_by_id(root: etree._Element, id: str) -> etree._Element | None:
     for company in root:
         if company.get("id") == id:
             return company

{python_materialsdb-0.1.0 → python_materialsdb-0.2.0}/src/materialsdb/classes.py

@@ -14,6 +14,12 @@ from dataclasses import dataclass
 from typing import Tuple, Optional, List
 
 
+class TDesignUsage(str):
+    xs_type: str = "simpleType"
+    xml_enum: Tuple[str, ...] = ('consDesignForWall', 'consDesignForRoof', 'consDesignForFloor')
+    xml_name: str = "TDesignUsage"
+
+
 class TLCADB(str):
     xs_type: str = "simpleType"
     xml_enum: Tuple[str, ...] = ('dbKBOB', 'dbOkobauDat', 'dbLux')
@@ -58,7 +64,7 @@ class T2Lowercase(str):
 
 class Groupkind(str):
     xs_type: str = "simpleType"
-    xml_enum: Tuple[str, ...] = ('Others', 'Water_Proof', 'Vapour_Proof', 'Concrete', 'Wood_Timberproducts', 'Insulation', 'Masonry', 'Metal', 'Mortar', 'Plastics', 'Stone', 'Composite', 'Films', 'Render', 'Covering', 'Glas', 'Soil', 'air')
+    xml_enum: Tuple[str, ...] = ('Others', 'Water_Proof', 'Vapour_Proof', 'Concrete', 'Wood_Timberproducts', 'Insulation', 'Masonry', 'Metal', 'Mortar', 'Plastics', 'Stone', 'Composite', 'Films', 'Render', 'Covering', 'Glas', 'Soil', 'Air')
     xml_name: str = "groupkind"
 
 
@@ -408,9 +414,10 @@ class Lcia:
 @dataclass
 class Lcaversion:
     id: str
-    code: Brackguid
     xs_type: str = "element"
-    xml_attributes: Tuple[str, ...] = ('id', 'code')
+    code: Optional[Brackguid] = None
+    disabled: Optional[Boolean] = None
+    xml_attributes: Tuple[str, ...] = ('id', 'code', 'disabled')
     xml_name = "lcaversion"
     xml_elements: Tuple[str, ...] = ()
 
@@ -555,11 +562,11 @@ class Vlca:
 @dataclass
 class Variation:
     id: Guid
-    vgeometry: List[Vgeometry]
-    vthermal: List[Vthermal]
     xs_type: str = "element"
     displayorder: Optional[int] = None
     xml_attributes: Tuple[str, ...] = ('id', 'displayorder')
+    vgeometry: Optional[List[Vgeometry]] = None
+    vthermal: Optional[List[Vthermal]] = None
     vacoustic: Optional[List[Vacoustic]] = None
     vother: Optional[List[Vother]] = None
     vlcia: Optional[List[Vlcia]] = None
@@ -582,7 +589,8 @@ class Construction:
     xs_type: str = "element"
     source: Optional[str] = None
     consref: Optional[str] = None
-    xml_attributes: Tuple[str, ...] = ('source', 'consref')
+    designusage: Optional[TDesignUsage] = None
+    xml_attributes: Tuple[str, ...] = ('source', 'consref', 'designusage')
     xml_name = "construction"
     xml_elements: Tuple[str, ...] = ()
 

{python_materialsdb-0.1.0 → python_materialsdb-0.2.0}/src/materialsdb/config.py

@@ -1,14 +1,11 @@
+import json
 import os
 import pathlib
-import json
-from typing import Dict
 
 
 def get_config_dir():
     config_dir = pathlib.Path(
-        os.environ.get("APPDATA")
-        or os.environ.get("XDG_CACHE_HOME")
-        or pathlib.Path.home() / ".config"
+        os.environ.get("APPDATA") or os.environ.get("XDG_CACHE_HOME") or pathlib.Path.home() / ".config"
     ).joinpath(
         "materialsdb",
     )
@@ -20,7 +17,7 @@ def get_base_config_path() -> pathlib.Path:
     return get_config_dir() / "config.json"
 
 
-def get_base_config() -> Dict[str, str]:
+def get_base_config() -> dict[str, str]:
     base_config_path = get_base_config_path()
     if base_config_path.exists():
         return json.loads(get_base_config_path().read_text("utf-8"))