Metadata-Version: 2.1
Name: xknxproject
Version: 1.1.0
Summary: A library to gather information from ETS project files used for KNX
Home-page: UNKNOWN
Author: Marvin Wichmann
Author-email: me@marvin-wichmann.de
License: GNU GPL
Download-URL: https://github.com/XKNX/xknxproject/archive/1.1.0.zip
Keywords: knx eib ets ets5 ets6
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Description-Content-Type: text/markdown
License-File: LICENSE

# (X)KNX Project

[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=f8b424)](https://github.com/pre-commit/pre-commit)
[![Discord](https://img.shields.io/discord/338619021215924227?color=7289da&label=Discord&logo=discord&logoColor=7289da)](https://discord.gg/bkZe9m4zvw)
[![codecov](https://codecov.io/gh/XKNX/xknxproject/branch/main/graph/badge.svg?token=LgPvZpKK3k)](https://codecov.io/gh/XKNX/xknxproject)

Extracts KNX projects and asynchronously parses the underlying XML.

This project aims to provide a library that can be used to extract and parse KNX project files and read out useful information including
the group addresses, devices and their descriptions and possibly more.

## Documentation

Currently, xknxproject supports extracting (password protected) ETS5 and ETS6 files and can obtain the following information from your project:

* Areas, Lines, Devices and their individual address
* CommunicationObjectInstance references for their devices (GA assignments)
* Group Addresses and their DPT type if set
* The application programs communication objects and their respective flags and the DPT Type
* Location information of your devices (in which rooms they are)

Caution: Loading a middle-sized project with this tool takes about 1.5 seconds. For bigger projects this might as well be >3s.

## Installation

In order to parse XML and to overcome the performance issues that parsing application programs with over 800k lines of XML has we use lxml.
lxml requires libxml2 to be installed in the underlying system. You can read more on their documentation on this topic.

    pip install xknxproject

## Usage

```python
    import asyncio
    from xknxproject.models import KNXProject
    from xknxproject import KNXProj


    async def main():
        """Extract and parse a KNX project file."""
        knxproj: KNXProj = KNXProj("path/to/your/file.knxproj", "optional_password")
        project: KNXProject = await knxproj.parse()

    asyncio.run_until_complete(main())
```

The `KNXProject` is a typed dictionary and can be used just like a dictionary, or, exported as JSON.
You can find an example file (exported JSON) in our test suite under https://github.com/XKNX/xknxproject/tree/main/test/resources/stubs

The full type definition can be found here: https://github.com/XKNX/xknxproject/blob/main/xknxproject/models/knxproject.py


