xmi 0.4.0

Used to interpret XMI Schema

XMI Schema Python Library

A Python library for interpreting and managing XMI (Cross Model Information) schema data. XMI is an open-source schema for representing built environment information using graph methodology.

Overview

The xmi-schema-python library provides a robust framework for reading, parsing, and managing structural data from JSON dictionaries, converting them into structured Python objects that represent materials, cross-sections, members, connections, and geometric elements.

Features

• Two parallel implementations (v1 and v2) with different architectural approaches
• Comprehensive entity support for structural engineering elements
• Pydantic-based validation (v2) for type safety and data integrity
• Shape parameter system supporting 18+ cross-section types
• Relationship tracking between entities
• Error handling with detailed logging
• Well-tested with 138 unit tests and 72% code coverage

Installation

pip install xmi

Development Installation

git clone https://github.com/xmi-schema/xmi-schema-python.git
cd xmi-schema-python
poetry install

Quick Start

Using v2 (Recommended - Pydantic-based)

from xmi.v2.models.xmi_model.xmi_manager import XmiManager
import json

# Load XMI data from JSON file
with open('your_xmi_data.json', 'r') as f:
    xmi_dict = json.load(f)

# Parse the XMI data
manager = XmiManager()
xmi_model = manager.read_xmi_dict(xmi_dict)

# Access entities
materials = [e for e in xmi_model.entities
             if e.__class__.__name__ == 'XmiStructuralMaterial']
members = [e for e in xmi_model.entities
           if e.__class__.__name__ == 'XmiStructuralCurveMember']

# Check for errors
if xmi_model.errors:
    for error in xmi_model.errors:
        print(f"Error: {error.message}")

Using v1 (Legacy - Slots-based)

from xmi.v1.xmi_manager import XmiManager
import json

# Load and parse XMI data
with open('your_xmi_data.json', 'r') as f:
    xmi_dict = json.load(f)

manager = XmiManager()
xmi_model = manager.read_xmi_dict(xmi_dict)

# Access entities
materials = [e for e in xmi_model.entities
             if isinstance(e, XmiStructuralMaterial)]

Implemented Entities

Core Structural Entities

Entity Name	v1 Status	v2 Status	Description
StructuralMaterial			Material definitions (concrete, steel, timber, etc.)
StructuralPointConnection			Nodal points in 3D space with coordinates
StructuralCrossSection			Cross-section definitions with shape parameters
StructuralCurveMember			Linear structural members (beams, columns, braces)
StructuralSurfaceMember			Surface elements (slabs, walls, plates)
StructuralStorey			Building level/storey definitions
StructuralUnit			Unit system definitions (SI, Imperial)
StructuralModel			Top-level model container

Geometry Classes

Geometry Type	v1 Status	v2 Status	Description
Point3D			3D point coordinates (X, Y, Z)
Line3D			Linear segments between two points
Arc3D			Circular arc segments with center point
Segment			Generic segment wrapper for geometry

Relationship Types

Relationship	v1 Status	v2 Status	Purpose
HasStructuralMaterial			Links entities to material definitions
HasCrossSection			Links members to cross-section definitions
HasStructuralNode			Links members to point connections
HasSegment			Links members to geometric segments
HasGeometry			Links entities to geometric elements
HasLine3D			Links segments to line geometry
HasPoint3D			Links entities to point geometry
HasStructuralStorey			Links entities to storey definitions

Supported Cross-Section Shapes

The library supports 18 different cross-section shape types with strongly-typed parameters:

Solid Sections

• Circular - Parameters: D (diameter)
• Rectangular - Parameters: H (height), B (width)

Structural Steel Shapes

• I-Shape - Parameters: D, B, T (flange thickness), t (web thickness), r (radius)
• C-Shape - Parameters: D, B, T, t, r
• T-Shape - Parameters: D, B, T, t, r
• L-Shape - Parameters: D, B, T, t

Hollow Sections

• Circular Hollow - Parameters: D (outer diameter), T (wall thickness)
• Square Hollow - Parameters: D (outer dimension), T (wall thickness)
• Rectangular Hollow - Parameters: H (height), B (width), T (wall thickness)

Specialty Shapes

• Trapezium - Parameters: H, B1 (top width), B2 (bottom width)
• Polygon - Parameters: N (number of sides), R (circumradius)

Angle Sections

• Equal Angle - Parameters: D, B, T, t
• Unequal Angle - Parameters: D, B, T1, T2, t

Bar Sections

• Flat Bar - Parameters: H, B
• Square Bar - Parameters: D
• Round Bar - Parameters: D
• Deformed Bar - Parameters: D

Custom

• Custom - Flexible parameters for non-standard shapes
• Unknown - Fallback for unrecognized shapes

Architecture

v1 Implementation (src/xmi/v1/)

• Memory-efficient using __slots__
• Manual property setters/getters
• Procedural entity creation in XmiManager.read_xmi_dict()
• Direct dictionary parsing

v2 Implementation (src/xmi/v2/)

• Pydantic models for validation and type safety
• Modular architecture with entity type mappings
• Mapping-based entity resolution via ENTITY_CLASS_MAPPING
• XmiModel.load_from_dict() handles instantiation
• Located in src/xmi/v2/utils/xmi_entity_type_mapping.py

Key Differences

• v1: Procedural parsing with explicit entity creation logic
• v2: Declarative mapping approach with automatic type resolution

Development

Running Tests

# Run all tests
poetry run pytest

# Run tests with coverage
poetry run pytest --cov=src/xmi --cov-report=html --cov-report=term

# Run specific test suite
poetry run pytest tests/xmi/v2/

# Run specific test file
poetry run pytest tests/xmi/v2/test_entities/test_xmi_structural_material.py

Test Coverage

Current test coverage: ~72% (188 tests passing)

• v1 Coverage: ~75% average
• v2 Coverage: ~85% average
• Total Tests: 188 passing
• Coverage Report: Generated in htmlcov/index.html

Generating Coverage Reports Locally

# Generate coverage report with HTML output
poetry run pytest --cov=src/xmi --cov-report=html --cov-report=term

# Open the HTML report in your browser
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux
start htmlcov/index.html  # Windows

Coverage in CI/CD

Coverage is automatically calculated on every PR:

• PR Validation: Runs tests with coverage on Python 3.12
• Coverage Comment: Bot comments coverage metrics on PRs
• Artifacts: HTML coverage reports are uploaded as workflow artifacts
• No Cloud Service: All coverage processing happens locally in GitHub Actions

The PR validation workflow will:

1. Run all tests with coverage tracking
2. Generate XML and HTML coverage reports
3. Calculate coverage percentage
4. Post a comment on the PR with coverage metrics
5. Upload the full HTML report as an artifact (downloadable for 30 days)

Building the Package

# Build distribution
poetry build

# Install locally (Linux/Mac)
bash install_package.sh

# Install locally (Windows)
setup_and_install.bat

Project Structure

xmi-schema-python/
├── src/xmi/
│   ├── v1/                      # Legacy implementation
│   │   ├── entities/            # Entity classes with __slots__
│   │   ├── enums/               # Enumeration types
│   │   ├── geometries/          # 3D geometry classes
│   │   ├── relationships/       # Entity relationships
│   │   ├── shapes/              # Shape definitions
│   │   ├── xmi_manager.py       # Entry point for v1
│   │   └── xmi_model.py         # Model container
│   │
│   └── v2/                      # Modern Pydantic implementation
│       ├── models/
│       │   ├── bases/           # Base classes for entities/relationships
│       │   ├── entities/        # Pydantic entity models
│       │   ├── enums/           # Typed enumerations
│       │   ├── geometries/      # Pydantic geometry models
│       │   ├── relationships/   # Pydantic relationship models
│       │   ├── shape_parameters/# Strongly-typed shape parameters
│       │   └── xmi_model/       # Model and manager
│       └── utils/
│           ├── xmi_entity_type_mapping.py  # Entity type mappings
│           └── xmi_errors.py    # Error definitions
│
├── tests/                       # Comprehensive test suite
│   ├── xmi/v1/                 # v1 tests
│   └── xmi/v2/                 # v2 tests
│
├── .github/workflows/           # CI/CD workflows
│   ├── pr-validation.yml       # PR test validation
│   └── python-publish.yml      # PyPI publishing
│
├── pyproject.toml              # Poetry configuration
├── pytest.ini                  # Pytest configuration
└── README.md                   # This file

Error Handling

Both versions include comprehensive error handling:

# Errors are accumulated without stopping execution
xmi_model = manager.read_xmi_dict(xmi_dict)

# Check for parsing errors
if xmi_model.errors:
    for error in xmi_model.errors:
        print(f"Entity: {error.entity_type}")
        print(f"Index: {error.entity_index}")
        print(f"Message: {error.message}")
        if error.raw_object:
            print(f"Raw data: {error.raw_object}")

Error Types (v2)

• XmiError - Base error class
• XmiInconsistentDatatypeError - Type mismatch errors
• XmiMissingReferenceInstanceError - Missing entity references
• XmiMissingRequiredAttributeError - Required field missing

CI/CD

The project uses GitHub Actions for continuous integration:

Pull Request Validation

• Runs on all PRs to main branch
• Tests against Python 3.9, 3.10, 3.11, 3.12
• All tests must pass before merging
• Uses Poetry for dependency management
• Cached dependencies for faster builds

Publishing Workflow

• Automatic semantic versioning
• Publishes to PyPI on merge to main
• Creates GitHub releases with artifacts
• Updates version in pyproject.toml

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Ensure all tests pass: poetry run pytest
5. Submit a pull request

Adding New Entities (v2)

1. Create entity class in src/xmi/v2/models/entities/
2. Add tests in tests/xmi/v2/test_entities/
3. Add to ENTITY_CLASS_MAPPING in xmi_entity_type_mapping.py
4. If relationships exist, add to RELATIONSHIP_CLASS_MAPPING
5. Update dependency order in _rearrange_xmi_dict() if needed

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• PyPI: https://pypi.org/project/xmi/
• GitHub: https://github.com/xmi-schema/xmi-schema-python
• XMI Schema: https://xmi-schema.org
• Documentation: [Coming soon]

Acknowledgments

Based on the XMI Schema specification and inspired by the C# implementation:

• XMI Schema C#
• Shape Parameters Reference

Version History

• v0.3.0 - Added shape parameters, improved v2 implementation
• v0.2.x - Enhanced entity support, improved testing
• v0.1.x - Initial release with v1 implementation

---

Status Legend:

• - Fully implemented and tested
• - Partially implemented
• - Not yet implemented