### Access Project Info and Set Language

Source: https://context7.com/xknx/xknxproject/llms.txt

Parses a KNX project to retrieve information such as creation details, tool version, schema version, and group address style. Demonstrates how to initialize XKNXProj with different language settings for localized translations.

```python
from xknxproject import XKNXProj
from xknxproject.models import GroupAddressStyle

knxproj = XKNXProj(path="project.knxproj")
project = knxproj.parse()

# Check project info for version and style
info = project["info"]
print(f"Created by: {info['created_by']}")  # e.g., "ETS5", "ETS6"
print(f"Tool version: {info['tool_version']}")
print(f"Schema version: {info['schema_version']}")

# Group address style determines address format
style = info["group_address_style"]
print(f"Group address style: {style}")

# Examples of address formats based on style:
# - ThreeLevel: "1/2/3" (main/middle/sub)
# - TwoLevel: "1/123" (main/sub)
# - Free: "12345" (numeric)

# Parse with specific language for translations
knxproj_de = XKNXProj(
    path="project.knxproj",
    language="de-DE"  # German
)
project_de = knxproj_de.parse()

knxproj_en = XKNXProj(
    path="project.knxproj",
    language="en-US"  # English
)
project_en = knxproj_en.parse()
```

--------------------------------

### Extract and Parse KNX Project File

Source: https://github.com/xknx/xknxproject/blob/main/README.md

Instantiate XKNXProj with the path to your .knxproj file, an optional password, and an optional language code. Then, call the parse method to obtain a typed dictionary representing the KNX project data.

```python
from xknxproject.models import KNXProject
from xknxproject import XKNXProj


knxproj: XKNXProj = XKNXProj(
    path="path/to/your/file.knxproj",
    password="password",  # optional
    language="de-DE",  # optional
)
project: KNXProject = knxproj.parse()
```

--------------------------------

### Parse KNX Project with XKNXProj

Source: https://context7.com/xknx/xknxproject/llms.txt

Instantiate XKNXProj to parse a KNX project file. Supports password-protected projects and specifies language for translations. Accesses project info and exports to JSON.

```python
from xknxproject import XKNXProj
from xknxproject.models import KNXProject
import json

# Basic usage - parse a project file without password
knxproj = XKNXProj(path="path/to/project.knxproj")
project: KNXProject = knxproj.parse()

# Parse a password-protected project with specific language
knxproj = XKNXProj(
    path="path/to/protected_project.knxproj",
    password="mypassword",
    language="de-DE",  # German language for translations
)
project = knxproj.parse()

# Access project information
print(f"Project: {project['info']['name']}")
print(f"Created by: {project['info']['created_by']}")
print(f"Tool version: {project['info']['tool_version']}")
print(f"Group address style: {project['info']['group_address_style']}")

# Export parsed project to JSON
with open("project_export.json", "w") as f:
    json.dump(project, f, indent=2)
```

--------------------------------

### Access KNX Topology

Source: https://context7.com/xknx/xknxproject/llms.txt

Access the KNX topology structure, including areas, lines, and devices, to retrieve hardware and manufacturer details. Initialize and parse the XKNXProj object to access this data.

```python
from xknxproject import XKNXProj
from xknxproject.models import Device, Area, Line, Channel

knxproj = XKNXProj(path="project.knxproj")
project = knxproj.parse()

# Access topology structure
for area_addr, area in project["topology"].items():
    print(f"Area {area_addr}: {area['name']}")
    for line_addr, line in area["lines"].items():
        print(f"  Line {area_addr}.{line_addr}: {line['name']}")
        print(f"    Medium: {line['medium_type']}")
        print(f"    Devices: {len(line['devices'])}")

# Get detailed device information
for device_addr, device in project["devices"].items():
    print(f"\nDevice: {device_addr}")
    print(f"  Name: {device['name']}")
    print(f"  Hardware: {device['hardware_name']}")
    print(f"  Manufacturer: {device['manufacturer_name']}")
    print(f"  Order number: {device['order_number']}")
    print(f"  Application: {device['application']}")

    # List device channels
    if device["channels"]:
        print("  Channels:")
        for ch_id, channel in device["channels"].items():
            print(f"    - {channel['name']}")
            print(f"      Objects: {len(channel['communication_object_ids'])}")
```

--------------------------------

### Print Building Location Hierarchy

Source: https://context7.com/xknx/xknxproject/llms.txt

Recursively print the building location hierarchy, including spaces, their types, names, usage text, assigned devices, and functions. This function requires a parsed XKNXProj object.

```python
from xknxproject import XKNXProj
from xknxproject.models import Space

knxproj = XKNXProj(path="project.knxproj")
project = knxproj.parse()

def print_spaces(spaces: dict, indent: int = 0):
    """Recursively print space hierarchy."""
    for name, space in spaces.items():
        prefix = "  " * indent
        print(f"{prefix}{space['type']}: {space['name']}")
        if space["usage_text"]:
            print(f"{prefix}  Usage: {space['usage_text']}")
        if space["devices"]:
            print(f"{prefix}  Devices: {', '.join(space['devices'])}")
        if space["functions"]:
            print(f"{prefix}  Functions: {len(space['functions'])}")
        # Recurse into sub-spaces
        if space["spaces"]:
            print_spaces(space["spaces"], indent + 1)

# Print complete location hierarchy
print("Building Structure:")
print_spaces(project["locations"])
```

--------------------------------

### Iterate and Display Functions

Source: https://context7.com/xknx/xknxproject/llms.txt

Parses a KNX project and iterates through all defined functions, printing their names, types, usage text, space IDs, and associated group addresses with their roles. Requires 'project.knxproj' to be present.

```python
from xknxproject import XKNXProj
from xknxproject.models import Function, GroupAddressRef

knxproj = XKNXProj(path="project.knxproj")
project = knxproj.parse()

# Iterate over all functions
for func_id, func in project["functions"].items():
    print(f"\nFunction: {func['name']}")
    print(f"  Type: {func['function_type']}")
    print(f"  Usage: {func['usage_text']}")
    print(f"  Space ID: {func['space_id']}")

    # List associated group addresses with their roles
    print("  Group Addresses:")
    for ga_addr, ga_ref in func["group_addresses"].items():
        print(f"    - {ga_addr}: {ga_ref['name']} (Role: {ga_ref['role']})")
```

--------------------------------

### Safe KNX Project Parsing with Exception Handling

Source: https://context7.com/xknx/xknxproject/llms.txt

Safely parses a KNX project file, handling specific exceptions such as invalid passwords, missing project files, and unexpected content. Returns the parsed project data or None if an error occurs. Specify the project path and optionally a password.

```python
from xknxproject import XKNXProj
from xknxproject.exceptions import (
    XknxProjectException,
    InvalidPasswordException,
    ProjectNotFoundException,
    UnexpectedFileContent,
)

def parse_project_safely(path: str, password: str = None):
    """Parse a KNX project with proper error handling."""
    try:
        knxproj = XKNXProj(path=path, password=password)
        return knxproj.parse()
    except InvalidPasswordException:
        print("Error: Invalid password or password required")
        return None
    except ProjectNotFoundException:
        print("Error: Project signature not found in archive")
        return None
    except UnexpectedFileContent as e:
        print(f"Error: Unexpected file content - {e}")
        return None
    except XknxProjectException as e:
        print(f"General parsing error: {e}")
        return None

# Usage
project = parse_project_safely("project.knxproj", "wrong_password")
if project:
    print(f"Successfully parsed: {project['info']['name']}")
```

--------------------------------

### Find Rooms with Devices

Source: https://context7.com/xknx/xknxproject/llms.txt

Find all rooms within the building location hierarchy that have assigned devices. This function recursively searches through spaces and returns a list of rooms containing devices. Requires a parsed XKNXProj object.

```python
from xknxproject import XKNXProj
from xknxproject.models import Space

knxproj = XKNXProj(path="project.knxproj")
project = knxproj.parse()

# Find all rooms with devices
def find_rooms_with_devices(spaces: dict, rooms: list = None):
    if rooms is None:
        rooms = []
    for space in spaces.values():
        if space["type"] == "Room" and space["devices"]:
            rooms.append(space)
        find_rooms_with_devices(space["spaces"], rooms)
    return rooms

rooms = find_rooms_with_devices(project["locations"])
for room in rooms:
    print(f"\nRoom: {room['name']}")
    for device_addr in room["devices"]:
        device = project["devices"].get(device_addr)
        if device:
            print(f"  - {device['name']} ({device_addr})")
```

--------------------------------

### Print Group Ranges Structure

Source: https://context7.com/xknx/xknxproject/llms.txt

Parses a KNX project file and recursively prints the structure of group ranges, including their names, address ranges, and associated group addresses. Ensure the 'project.knxproj' file is accessible.

```python
from xknxproject import XKNXProj
from xknxproject.models import GroupRange

knxproj = XKNXProj(path="project.knxproj")
project = knxproj.parse()

def print_group_ranges(ranges: dict, indent: int = 0):
    """Recursively print group range hierarchy."""
    for addr, gr in ranges.items():
        prefix = "  " * indent
        print(f"{prefix}{addr}: {gr['name']}")
        print(f"{prefix}  Address range: {gr['address_start']} - {gr['address_end']}")
        if gr["group_addresses"]:
            print(f"{prefix}  Group addresses: {', '.join(gr['group_addresses'])}")
        if gr["comment"]:
            print(f"{prefix}  Comment: {gr['comment']}")
        # Recurse into sub-ranges
        if gr["group_ranges"]:
            print_group_ranges(gr["group_ranges"], indent + 1)

print("Group Address Structure:")
print_group_ranges(project["group_ranges"])
```

--------------------------------

### Access KNX Project Data Structure

Source: https://context7.com/xknx/xknxproject/llms.txt

Parse a KNX project and iterate through its structured data. Accesses project metadata, device details including manufacturer and application, and group addresses with DPT information.

```python
from xknxproject import XKNXProj
from xknxproject.models import KNXProject, Device, GroupAddress, CommunicationObject

knxproj = XKNXProj(path="project.knxproj", password="test")
project: KNXProject = knxproj.parse()

# Access project metadata
info = project["info"]
print(f"Project ID: {info['project_id']}")
print(f"Schema version: {info['schema_version']}")
print(f"Last modified: {info['last_modified']}")

# Iterate over all devices
for address, device in project["devices"].items():
    print(f"Device {address}: {device['name']}")
    print(f"  Manufacturer: {device['manufacturer_name']}")
    print(f"  Order number: {device['order_number']}")
    print(f"  Application: {device['application']}")
    print(f"  Communication objects: {len(device['communication_object_ids'])}")

# Access group addresses with DPT information
for ga_address, ga in project["group_addresses"].items():
    dpt_info = f"DPT {ga['dpt']['main']}.{ga['dpt']['sub']}" if ga['dpt'] else "No DPT"
    print(f"{ga_address} - {ga['name']} ({dpt_info})")
    if ga['data_secure']:
        print("  [Data Secure enabled]")
```

--------------------------------

### Iterate Communication Objects

Source: https://context7.com/xknx/xknxproject/llms.txt

Iterate over all communication objects in a KNX project to access their properties like name, text, function, device, size, capabilities, DPT information, and group address links. Requires the XKNXProj object to be initialized and parsed.

```python
from xknxproject import XKNXProj
from xknxproject.models import CommunicationObject, Flags

knxproj = XKNXProj(path="project.knxproj", password="test")
project = knxproj.parse()

# Iterate over all communication objects
for co_id, co in project["communication_objects"].items():
    print(f"Object: {co_id}")
    print(f"  Name: {co['name']}")
    print(f"  Text: {co['text']}")
    print(f"  Function: {co['function_text']}")
    print(f"  Device: {co['device_address']}")
    print(f"  Object size: {co['object_size']}")

    # Check communication flags
    flags = co["flags"]
    capabilities = []
    if flags["read"]:
        capabilities.append("Read")
    if flags["write"]:
        capabilities.append("Write")
    if flags["transmit"]:
        capabilities.append("Transmit")
    if flags["update"]:
        capabilities.append("Update")
    print(f"  Capabilities: {', '.join(capabilities)}")

    # DPT information
    for dpt in co["dpts"]:
        print(f"  DPT: {dpt['main']}.{dpt['sub'] or 'x'}")

    # Linked group addresses
    print(f"  Group addresses: {', '.join(co['group_address_links'])}")
```

--------------------------------

### Query Group Addresses by DPT

Source: https://context7.com/xknx/xknxproject/llms.txt

Filter group addresses based on Datapoint Type (DPT) main and sub-numbers. Retrieves linked communication objects for switching addresses and raw address/project UID for temperature sensors.

```python
from xknxproject import XKNXProj
from xknxproject.models import GroupAddress, DPTType

knxproj = XKNXProj(path="project.knxproj")
project = knxproj.parse()

# Find all group addresses for lighting (DPT 1.x - switching)
switching_addresses = [
    (addr, ga)
    for addr, ga in project["group_addresses"].items()
    if ga["dpt"] and ga["dpt"]["main"] == 1
]

for addr, ga in switching_addresses:
    print(f"Switch: {addr} - {ga['name']}")
    # Get linked communication objects
    for co_id in ga["communication_object_ids"]:
        co = project["communication_objects"][co_id]
        print(f"  Linked to: {co['device_address']} - {co['text']}")

# Find temperature sensors (DPT 9.001)
temp_addresses = [
    (addr, ga)
    for addr, ga in project["group_addresses"].items()
    if ga["dpt"] and ga["dpt"]["main"] == 9 and ga["dpt"]["sub"] == 1
]

for addr, ga in temp_addresses:
    print(f"Temperature: {addr} - {ga['name']}")
    print(f"  Raw address: {ga['raw_address']}")
    print(f"  Project UID: {ga['project_uid']}")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.