Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Parse D-Bus introspection XML and process it in various ways

Project description

dbus-deviation

dbus-deviation is a project for parsing D-Bus introspection XML and processing it in various ways. Its main tool is dbus-interface-diff, which calculates the difference between two D-Bus APIs for the purpose of checking for API breaks. This functionality is also available as a Python module, dbusdeviation.

A second Python module, dbusapi, is provided for parsing D-Bus introspection XML to produce an AST representing a D-Bus interface.

dbus-deviation’s API is currently unstable and is likely to change wildly.

Using dbus-deviation

dbus-deviation can be used as a utility program or as a Python library.

The utility programs:

  • dbus-interface-diff: Check for differences between two versions of the same D-Bus API and print details of each difference. It can check for problems with forwards and backwards compatibility, as well as general informational differences.

    Example: dbus-interface-diff
    com.example.Interface1.xml \ # old version of the interface com.example.Interface2.xml # new version of the interface

  • dbus-interface-vcs-helper: This is a helper program designed to be used by dbus-deviation.mk.

As a library, the core object is an InterfaceParser, allowing a D-Bus API to be parsed and represented as an AST. See the API documentation for more explanation and examples.

dbus-deviation.mk

This is a Makefile snippet which should be copied into your project, added to git, and the following two lines included in your top-level Makefile.am:

dbus_api_xml_files = list of D-Bus interface XML files
-include $(top_srcdir)/dbus-deviation.mk

Do not add it to EXTRA_DIST. It is designed to work from git checkouts only.

Then run:

make dbus-deviation-mk-install

to set up the API signature database. This assumes that your project defines D-Bus interfaces in XML files, and does not generate them at runtime.

Finally, copy pre-push.hook to .git/hooks/pre-push and ensure it’s executable. This script will automatically update the API signature database when a new release tag is pushed to the git remote.

There is currently no streamlined support for projects which generate D-Bus interfaces at runtime.

dbus-deviation.mk defines the following rules:

  • dist-dbus-api-compatibility (a dependency of dist-hook)
  • check-dbus-api-compatibility (a dependency of check-local)
  • dbus-deviation-mk-install (never triggered automatically)

Dependencies

  • argparse
  • lxml

Development

For fun, dbus-deviation uses the following services to do continuous integration and gather build statistics:

Licensing

dbus-deviation is licensed under the LGPL version 2.1 (or, at your option, any later version). See COPYING for more details.

dbus-deviation versions 0.4.0 and earlier were licensed under the choice of the Academic Free License version 2.1, or the GNU General Public License version 2 (or, at your option, any later version). This is the same license as D-Bus itself. Version 0.5.0 was relicensed to LGPLv2.1+ as it’s a more standard license with less ambiguity about its implications.

Bugs

Bug reports and patches should be sent via GitHub or Gitlab:

Contact

Philip Withnall philip@tecnocode.co.uk https://tecnocode.co.uk/dbus-deviation/

Overview of changes from dbus-deviation 0.6.0 to dbus-deviation 0.6.1

Major changes:

  • Drop support for Python 2.7
  • Move to pycodestyle from pep8 and drop setup.py requirement for it
  • Minor maintenance documentation updates

Overview of changes from dbus-deviation 0.5.0 to dbus-deviation 0.6.0

Major changes:

  • Split out the logging API to allow for reuse
  • Expose source line numbers in dbusapi.ast
  • Add a D-Bus type parser, dbusapi.typeparser (thanks to Kaloyan Tenchov)
  • Drop Python 3.3 support as Sphinx no longer supports it
  • Add a D-Bus type formatter, dbusapi.typeformatter

Overview of changes from dbus-deviation 0.4.0 to dbus-deviation 0.5.0

Major changes:

  • Add support for <node> elements (Kaloyan Tenchov)
  • Add object path, interface name and callable name validation (Kaloyan Tenchov)
  • Relicense to LGPLv2.1+

Overview of changes from dbus-deviation 0.3.0 to dbus-deviation 0.4.0

Major changes:

  • Improve test coverage
  • Port to lxml instead of xml.etree
  • Support parsing comments and documentation nodes

Overview of changes from dbus-deviation 0.2.0 to dbus-deviation 0.3.0

Major changes:

  • Improve utility arguments and variables in dbus-deviation.mk and vcs-helper

Overview of changes from dbus-deviation 0.1.0 to dbus-deviation 0.2.0

Major changes:

  • Improve error reporting
  • Improve test coverage
  • Add Makefile snippet and helper program (vcs-helper) for use in other projects

Initial release of dbus-deviation 0.1.0

Major changes:

  • Initial version of the project

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for dbus-deviation, version 0.6.1
Filename, size File type Python version Upload date Hashes
Filename, size dbus_deviation-0.6.1-py3-none-any.whl (52.4 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size dbus-deviation-0.6.1.tar.gz (60.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page