pwithnall / dbus-deviation Goto Github PK

A project for parsing D-Bus introspection XML and processing it in various ways.

License: GNU Lesser General Public License v2.1

Python 82.37% HTML 13.22% Makefile 3.86% Shell 0.55%

dbus-deviation's Introduction

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 [email protected] https://tecnocode.co.uk/dbus-deviation/

dbus-deviation's People

Contributors

Stargazers

Watchers

Forkers

mathieuduponchelle zayfod s-t-e-v-e-n-k

dbus-deviation's Issues

Enhancement: expose line number information

I'd like to be able to link to the exact place a symbol is defined, clang exposes this information through node.location.lineno, node.location.filename for example, arguably the filename is always known in the dbus case so a simple node.lineno would be enough.

Slightly related, is there a reason for not having all the symbol types inherit from a base node class (which could conveniently have a comment attribute as well) ?

And usually abstract syntax trees can be walked with generic methods, which is useful for certain purposes, so having that base class expose node.children might be something to consider ?

Enhancement: expose a dbus-type to plain english method

Example : 'as' -> 'An array of strings'

Shouldn't be too tough, this is trivial to do for C when a decent AST is available for example. Is there any existing parsing mechanism of these types in dbus-deviation itself ?

Tests fail

======================================================================
ERROR: test_duplicate (dbusapi.tests.test_ast.TestAstLogging)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/tmp/dbus-deviation/dbusapi/tests/test_ast.py", line 248, in test_duplicate
    'AMethod': method,
  File "/tmp/dbus-deviation/dbusapi/ast.py", line 318, in __init__
    for child in (methods or {}).values() + (signals or {}).values() + \
TypeError: unsupported operand type(s) for +: 'dict_values' and 'dict_values'

======================================================================
ERROR: test_annotation_argument (dbusapi.tests.test_ast.TestAstNames)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/tmp/dbus-deviation/dbusapi/tests/test_ast.py", line 148, in test_annotation_argument
    'AMethod': method,
  File "/tmp/dbus-deviation/dbusapi/ast.py", line 318, in __init__
    for child in (methods or {}).values() + (signals or {}).values() + \
TypeError: unsupported operand type(s) for +: 'dict_values' and 'dict_values'
…

Relicense to LGPLv2.1+

Licensing under GPL/AFL was a mistake, and means that combining dbus-deviation with LGPL code (or copying LGPL code into it) is not possible or has non-obvious consequences.

I would like to relicense dbus-deviation to LGPLv2.1+.

From the output of $ git log --format=format:%an | sort -u, the current contributors are:

Kaloyan Tenchov
Mathieu Duponchelle
Philip Withnall

@zayfod, @MathieuDuponchelle, are you OK with relicensing, and if so can you please confirm that here?

Installation fails on clean machine

Hello,

on a clean Arch-Linux machine:

# pip install dbus-deviation
Collecting dbus-deviation
  Downloading dbus-deviation-0.6.0.tar.gz (59 kB)
     |████████████████████████████████| 59 kB 1.7 MB/s 
    ERROR: Command errored out with exit status 1:
     command: /usr/bin/python -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-install-9ca6wvgl/dbus-deviation/setup.py'"'"'; __file__='"'"'/tmp/pip-install-9ca6wvgl/dbus-deviation/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base /tmp/pip-pip-egg-info-s_3v_3hr
         cwd: /tmp/pip-install-9ca6wvgl/dbus-deviation/
    Complete output (45 lines):
    WARNING: The wheel package is not available.
    WARNING: The wheel package is not available.
      ERROR: Command errored out with exit status 1:
       command: /usr/bin/python -u -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-wheel-4ygx8_7s/setuptools-pep8/setup.py'"'"'; __file__='"'"'/tmp/pip-wheel-4ygx8_7s/setuptools-pep8/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' bdist_wheel -d /tmp/pip-wheel-hfqrnlfm
           cwd: /tmp/pip-wheel-4ygx8_7s/setuptools-pep8/
      Complete output (6 lines):
      usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
         or: setup.py --help [cmd1 cmd2 ...]
         or: setup.py --help-commands
         or: setup.py cmd --help
    
      error: invalid command 'bdist_wheel'
      ----------------------------------------
      ERROR: Failed building wheel for setuptools-pep8
    ERROR: Failed to build one or more wheels
    Traceback (most recent call last):
      File "/usr/lib/python3.9/site-packages/setuptools/installer.py", line 119, in fetch_build_egg
        subprocess.check_call(cmd)
      File "/usr/lib/python3.9/subprocess.py", line 373, in check_call
        raise CalledProcessError(retcode, cmd)
    subprocess.CalledProcessError: Command '['/usr/bin/python', '-m', 'pip', '--disable-pip-version-check', 'wheel', '--no-deps', '-w', '/tmp/tmplwtyu92w', '--quiet', 'setuptools_pep8']' returned non-zero exit status 1.
    
    The above exception was the direct cause of the following exception:
    
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/tmp/pip-install-9ca6wvgl/dbus-deviation/setup.py", line 87, in <module>
        setup(
      File "/usr/lib/python3.9/site-packages/setuptools/__init__.py", line 152, in setup
        _install_setup_requires(attrs)
      File "/usr/lib/python3.9/site-packages/setuptools/__init__.py", line 147, in _install_setup_requires
        dist.fetch_build_eggs(dist.setup_requires)
      File "/usr/lib/python3.9/site-packages/setuptools/dist.py", line 684, in fetch_build_eggs
        resolved_dists = pkg_resources.working_set.resolve(
      File "/usr/lib/python3.9/site-packages/pkg_resources/__init__.py", line 766, in resolve
        dist = best[req.key] = env.best_match(
      File "/usr/lib/python3.9/site-packages/pkg_resources/__init__.py", line 1051, in best_match
        return self.obtain(req, installer)
      File "/usr/lib/python3.9/site-packages/pkg_resources/__init__.py", line 1063, in obtain
        return installer(requirement)
      File "/usr/lib/python3.9/site-packages/setuptools/dist.py", line 743, in fetch_build_egg
        return fetch_build_egg(self, req)
      File "/usr/lib/python3.9/site-packages/setuptools/installer.py", line 121, in fetch_build_egg
        raise DistutilsError(str(e)) from e
    distutils.errors.DistutilsError: Command '['/usr/bin/python', '-m', 'pip', '--disable-pip-version-check', 'wheel', '--no-deps', '-w', '/tmp/tmplwtyu92w', '--quiet', 'setuptools_pep8']' returned non-zero exit status 1.
    ----------------------------------------
ERROR: Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.