idl-parser 0.2.2__tar.gz → 0.3.2__tar.gz

{idl_parser-0.2.2 → idl_parser-0.3.2}/.github/workflows/test.yml

@@ -33,6 +33,32 @@ jobs:
       - name: Run tests
         run: python -m unittest discover --start-directory tests --pattern '*_test.py' --top-level-directory . --verbose
 
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Run tests with coverage
+        run: |
+          python -m pip install coverage
+          python -m coverage run --branch --source=idl_parser -m unittest discover --start-directory tests --pattern '*_test.py' --top-level-directory .
+          python -m coverage report
+          python -m coverage xml
+
+      # Uploads coverage.xml to Codecov, which serves the README badge.
+      # Without the CODECOV_TOKEN secret the upload may be rejected; that
+      # must not fail the tests, so errors are not fatal.
+      - uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+
   lint:
     name: Check undefined names
     runs-on: ubuntu-latest

{idl_parser-0.2.2 → idl_parser-0.3.2}/.gitignore

@@ -4,3 +4,5 @@
 build/*
 dist/*docs/_build/
 docs/api/generated/
+coverage.xml
+.coverage

idl_parser-0.3.2/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "ms-python.vscode-pylance"
+  ]
+}

idl_parser-0.3.2/.vscode/launch.json

@@ -0,0 +1,21 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Python: unittest discover",
+      "type": "python",
+      "request": "launch",
+      "module": "unittest",
+      "args": [
+        "discover",
+        "-s",
+        "tests",
+        "-p",
+        "*_test.py",
+        "-v"
+      ],
+      "cwd": "${workspaceFolder}",
+      "justMyCode": true
+    }
+  ]
+}

idl_parser-0.3.2/.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+  "python.testing.unittestEnabled": true,
+  "python.testing.pytestEnabled": false,
+  "python.testing.unittestArgs": [
+    "-v",
+    "-s",
+    "${workspaceFolder}/tests",
+    "-p",
+    "*_test.py"
+  ],
+  "python.testing.cwd": "${workspaceFolder}",
+  "python.analysis.typeCheckingMode": "basic",
+  "python.analysis.autoImportCompletions": true,
+  "python.analysis.diagnosticMode": "workspace",
+  "files.trimTrailingWhitespace": true,
+  "editor.formatOnSave": true,
+  "editor.rulers": [
+    88
+  ],
+  "terminal.integrated.env.osx": {
+    "PYTHONPATH": "${workspaceFolder}${pathSeparator}${env:PYTHONPATH}"
+  }
+}

{idl_parser-0.2.2/idl_parser.egg-info → idl_parser-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idl_parser
-Version: 0.2.2
+Version: 0.3.2
 Summary: Very simple OMG IDL (Interface Definition Language) parser. This parses IDL files and outputs intermediate class objects.
 Author-email: ysuga <ysuga@ysuga.net>
 License-Expression: GPL-3.0-or-later
@@ -24,7 +24,7 @@ Dynamic: license-file
 idl_parser
 ============
 
-|Test Status| |Docs Status|
+|Test Status| |Coverage| |Docs Status|
 
 Description 
 -----------
@@ -99,9 +99,13 @@ Example
 
 More examples are in the ``examples`` folder of the repository:
 
-- ``example.py``: interfaces, typedefs, unions and structs
+- ``example.py``: the smallest example: a module and an interface
+- ``argument_direction_example.py``: directions of method arguments (``in``, ``out`` and ``inout``)
+- ``struct_example.py``: structs and their member types
+- ``enum_example.py``: enums and their values
 - ``union_example.py``: unions (discriminator kinds, case and ``default`` labels, member types)
 - ``annotation_example.py``: IDL 4 annotations (``@key``, ``@range``, ...) and struct keys
+- ``scoped_name_example.py``: same-named types in several modules (relative ``X``, ``C::X`` and absolute ``::B::X`` names)
 
 https://github.com/sugarsweetrobotics/idl_parser/tree/main/examples
 
@@ -128,3 +132,7 @@ Copyright
 .. |Docs Status| image:: https://readthedocs.org/projects/idl-parser/badge/?version=latest
    :target: https://idl-parser.readthedocs.io/en/latest/
    :alt: Documentation Status
+
+.. |Coverage| image:: https://codecov.io/gh/sugarsweetrobotics/idl_parser/branch/main/graph/badge.svg
+   :target: https://codecov.io/gh/sugarsweetrobotics/idl_parser
+   :alt: Coverage

{idl_parser-0.2.2 → idl_parser-0.3.2}/README.md

@@ -2,6 +2,7 @@
 
 [![Test](https://github.com/sugarsweetrobotics/idl_parser/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/sugarsweetrobotics/idl_parser/actions/workflows/test.yml)
 [![Documentation Status](https://readthedocs.org/projects/idl-parser/badge/?version=latest)](https://idl-parser.readthedocs.io/en/latest/)
+[![codecov](https://codecov.io/gh/sugarsweetrobotics/idl_parser/branch/main/graph/badge.svg)](https://codecov.io/gh/sugarsweetrobotics/idl_parser)
 
 
 ## Description 
@@ -74,9 +75,13 @@ More examples are in the [examples](examples/) folder:
 
 | File | Shows |
 |---|---|
-| [`example.py`](examples/example.py) | interfaces, typedefs, unions and structs |
+| [`example.py`](examples/example.py) | the smallest example: a module and an interface |
+| [`argument_direction_example.py`](examples/argument_direction_example.py) | directions of method arguments: `in`, `out` and `inout` |
+| [`struct_example.py`](examples/struct_example.py) | structs and their member types |
+| [`enum_example.py`](examples/enum_example.py) | enums and their values |
 | [`union_example.py`](examples/union_example.py) | unions: discriminator kinds, case and `default` labels, member types |
 | [`annotation_example.py`](examples/annotation_example.py) | IDL 4 annotations (`@key`, `@range`, ...) and struct keys |
+| [`scoped_name_example.py`](examples/scoped_name_example.py) | same-named types in several modules: relative (`X`, `C::X`) and absolute (`::B::X`) names |
 
 Run them with e.g. `python examples/union_example.py` (in a source checkout no install is needed).
 

{idl_parser-0.2.2 → idl_parser-0.3.2}/README.rst

@@ -1,7 +1,7 @@
 idl_parser
 ============
 
-|Test Status| |Docs Status|
+|Test Status| |Coverage| |Docs Status|
 
 Description 
 -----------
@@ -76,9 +76,13 @@ Example
 
 More examples are in the ``examples`` folder of the repository:
 
-- ``example.py``: interfaces, typedefs, unions and structs
+- ``example.py``: the smallest example: a module and an interface
+- ``argument_direction_example.py``: directions of method arguments (``in``, ``out`` and ``inout``)
+- ``struct_example.py``: structs and their member types
+- ``enum_example.py``: enums and their values
 - ``union_example.py``: unions (discriminator kinds, case and ``default`` labels, member types)
 - ``annotation_example.py``: IDL 4 annotations (``@key``, ``@range``, ...) and struct keys
+- ``scoped_name_example.py``: same-named types in several modules (relative ``X``, ``C::X`` and absolute ``::B::X`` names)
 
 https://github.com/sugarsweetrobotics/idl_parser/tree/main/examples
 
@@ -105,3 +109,7 @@ Copyright
 .. |Docs Status| image:: https://readthedocs.org/projects/idl-parser/badge/?version=latest
    :target: https://idl-parser.readthedocs.io/en/latest/
    :alt: Documentation Status
+
+.. |Coverage| image:: https://codecov.io/gh/sugarsweetrobotics/idl_parser/branch/main/graph/badge.svg
+   :target: https://codecov.io/gh/sugarsweetrobotics/idl_parser
+   :alt: Coverage

idl_parser-0.3.2/examples/argument_direction_example.py

@@ -0,0 +1,75 @@
+"""Example: read the direction of interface method arguments (in / out / inout).
+
+In IDL each argument of a method has a direction:
+
+- ``in``: the caller passes a value to the method,
+- ``out``: the method returns a value to the caller through the argument,
+- ``inout``: the caller passes a value and the method may change it.
+
+Shows how to
+- read each argument's direction (``direction``),
+- pick the arguments the caller sends and the ones it receives,
+- build a simple call signature from the directions.
+
+Run::
+
+    python examples/argument_direction_example.py
+"""
+import _path  # noqa: F401  (use the idl_parser of this checkout)
+
+from idl_parser import parser
+
+IDL = '''
+module my_module {
+  interface Counter {
+    // in: the value is only passed to the method
+    void set(in long value);
+
+    // out: the value is only returned from the method
+    void get(out long value);
+
+    // inout: the value is passed, changed and returned
+    void increment(inout long value);
+
+    // directions can be mixed in one method
+    boolean divide(in double a, in double b, out double quotient, inout long count);
+  };
+};
+'''
+
+
+def main():
+    global_module = parser.IDLParser().load(IDL)
+    counter = global_module.module_by_name('my_module').interface_by_name('Counter')
+
+    print('== Direction of each argument')
+    for m in counter.methods:
+        for a in m.arguments:
+            print('  %-10s %-9s %-6s %s' % (m.name, a.name, a.direction, a.type.name))
+    print()
+
+    # in and inout arguments are sent by the caller,
+    # out and inout arguments (and the return value) come back to the caller.
+    print('== What the caller sends and receives')
+    for m in counter.methods:
+        sends = [a.name for a in m.arguments if a.direction in ('in', 'inout')]
+        receives = [a.name for a in m.arguments if a.direction in ('out', 'inout')]
+        if m.returns.name != 'void':
+            receives.insert(0, '(return %s)' % m.returns.name)
+        print('  %-10s sends: %-14s receives: %s' % (m.name, ', '.join(sends) or '-', ', '.join(receives) or '-'))
+    print()
+
+    # For example, a Python-like signature: in/inout become parameters,
+    # out/inout and the return value become results.
+    print('== Python-like signatures')
+    for m in counter.methods:
+        params = [a.name for a in m.arguments if a.direction in ('in', 'inout')]
+        results = [a.name for a in m.arguments if a.direction in ('out', 'inout')]
+        if m.returns.name != 'void':
+            results.insert(0, 'result')
+        call = '%s(%s)' % (m.name, ', '.join(params))
+        print('  %s' % ('%s = %s' % (', '.join(results), call) if results else call))
+
+
+if __name__ == '__main__':
+    main()

idl_parser-0.3.2/examples/enum_example.py

@@ -0,0 +1,68 @@
+"""Example: read enums and their values.
+
+Shows how to get
+- the enums in a module (``enums``, ``enum_by_name``),
+- each enumerator's name and ordinal (``values``, ``value``),
+- an enumerator by name (``value_by_name``),
+- an enum used as a struct member and as a method return type.
+
+Run::
+
+    python examples/enum_example.py
+"""
+import _path  # noqa: F401  (use the idl_parser of this checkout)
+
+from idl_parser import parser
+
+IDL = '''
+module my_module {
+  enum Color {
+    RED,
+    GREEN,
+    BLUE
+  };
+
+  enum ReturnCode {
+    RETURN_OK,
+    RETURN_ERROR,
+    RETURN_TIMEOUT
+  };
+
+  struct Light {
+    Color color;
+    double brightness;
+  };
+
+  interface LightController {
+    ReturnCode setColor(in Color color);
+  };
+};
+'''
+
+
+def main():
+    global_module = parser.IDLParser().load(IDL)
+    my_module = global_module.module_by_name('my_module')
+
+    print('enums in my_module:', [e.name for e in my_module.enums])
+    print()
+
+    color = my_module.enum_by_name('Color')
+    print('enum %s' % color.full_path)
+    for v in color.values:
+        print('  %s = %d' % (v.name, v.value))
+    print('BLUE is', color.value_by_name('BLUE').value)
+    print()
+
+    # A struct member whose type is an enum
+    light = my_module.struct_by_name('Light')
+    member = light.member_by_name('color')
+    print('Light.color is enum? %s (%s)' % (member.type.is_enum, member.type.full_path))
+
+    # An enum as a method return type
+    method = my_module.interface_by_name('LightController').method_by_name('setColor')
+    print('setColor returns %s' % method.returns.name)
+
+
+if __name__ == '__main__':
+    main()

idl_parser-0.3.2/examples/example.py

@@ -0,0 +1,37 @@
+"""Example: parse an IDL string and print the methods of an interface.
+
+Run (no install needed in a checkout)::
+
+    python examples/example.py
+
+See also ``struct_example.py``, ``enum_example.py``, ``union_example.py``,
+``annotation_example.py`` and ``scoped_name_example.py`` in this folder.
+"""
+import _path  # noqa: F401  (use the idl_parser of this checkout)
+
+from idl_parser import parser
+
+IDL = '''
+module my_module {
+  interface Calculator {
+    long add(in long a, in long b);
+    void reset();
+    boolean divide(in double a, in double b, out double result);
+  };
+};
+'''
+
+
+def main():
+    global_module = parser.IDLParser().load(IDL)
+    my_module = global_module.module_by_name('my_module')
+    calculator = my_module.interface_by_name('Calculator')
+
+    print('interface %s' % calculator.full_path)
+    for m in calculator.methods:
+        args = ', '.join('%s %s %s' % (a.direction, a.type.name, a.name) for a in m.arguments)
+        print('  %s %s(%s)' % (m.returns.name, m.name, args))
+
+
+if __name__ == '__main__':
+    main()

idl_parser-0.3.2/examples/scoped_name_example.py

@@ -0,0 +1,121 @@
+"""Example: resolve type names across modules (relative and absolute names).
+
+When several modules define a type with the same name, a type name is
+resolved with the IDL scoping rules (issues #69, #72):
+
+- a relative name (``X``, ``C::X``) is looked up from the scope where it is
+  written, innermost first, then in the outer scopes;
+- an absolute name (``::B::X``) is looked up from the global scope only.
+
+Shows how to get
+- the definition a member, argument or return type refers to (``obj`` / ``type``),
+- the name as written (``ref_name``) and the name of the definition (``name``),
+- a typedef resolved in the scope where it is defined,
+- ``find_types()`` with and without a scope.
+
+Run::
+
+    python examples/scoped_name_example.py
+"""
+import _path  # noqa: F401  (use the idl_parser of this checkout)
+
+from idl_parser import parser
+
+IDL = '''
+// A global Point, and a Point in each module
+struct Point { long id; };
+
+module geometry {
+  struct Point { double x; double y; };
+  typedef Point Origin;       // geometry::Point (the scope of the typedef)
+
+  module d3 {
+    struct Point { double x; double y; double z; };
+  };
+};
+
+module robot {
+  struct Point { long joint; };
+
+  module arm {
+    struct Point { double angle; };
+
+    interface Controller {
+      // relative names: looked up from robot::arm, then robot, then global
+      Point            current();                    // robot::arm::Point
+      void             move_joint(in robot::Point p);  // robot::Point
+      void             move_to(in geometry::Point p);  // geometry::Point
+      void             move_to_3d(in geometry::d3::Point p);
+      // absolute names: from the global scope only
+      void             mark(in ::Point p);           // the global Point
+      void             move_arm(in ::robot::arm::Point p);
+      geometry::Origin origin();                     // typedef of geometry::Point
+    };
+  };
+
+  struct Pose {
+    Point                    joint;     // robot::Point
+    arm::Point               arm;       // relative name with a scope: robot::arm::Point
+    sequence<geometry::Point> path;     // element type is resolved too
+    ::Point                  marker;    // the global Point
+  };
+};
+'''
+
+
+def path(node):
+    """Full path of a definition ('' for the global scope is shown as '::')."""
+    p = node.full_path.lstrip(':')
+    return p if '::' in p else '::' + p
+
+
+def show(label, written, definition):
+    print('  %-22s %-24s -> %s' % (label, written, path(definition)))
+
+
+def main():
+    global_module = parser.IDLParser().load(IDL)
+    robot = global_module.module_by_name('robot')
+    arm = robot.module_by_name('arm')
+
+    print('robot::arm::Controller (name as written -> definition)')
+    controller = arm.interface_by_name('Controller')
+    for method in controller.methods:
+        if method.returns.name != 'void':
+            show(method.name + '() returns', method.returns.ref_name, method.returns.obj)
+        for a in method.arguments:
+            show(method.name + '(' + a.name + ')', a.type.ref_name, a.type.obj)
+    print()
+
+    # For a struct member, .type is the definition itself
+    print('robot::Pose members (member -> definition)')
+    pose = robot.struct_by_name('Pose')
+    for m in pose.members:
+        t = m.type
+        if t.is_sequence:
+            print('  %-22s -> sequence of %s' % (m.name, path(t.inner_type.obj)))
+        else:
+            print('  %-22s -> %s' % (m.name, path(t)))
+    print()
+
+    # The typedef is resolved where it is defined (module geometry),
+    # not where it is used (module robot::arm).
+    typedef = controller.method_by_name('origin').returns.obj
+    print('typedef %s -> %s' % (path(typedef), path(typedef.type)))
+    print()
+
+    # type.name is the name of the definition, without its scope
+    t = controller.method_by_name('move_to').arguments[0].type
+    print('name: %s, ref_name: %s, full path: %s' % (t.name, t.ref_name, path(t.obj)))
+    print()
+
+    # find_types(): with a scope the IDL scoping rules are used;
+    # without one, every definition with that name is returned.
+    print('find_types("Point", scope=robot::arm):', [path(n) for n in global_module.find_types('Point', scope=arm)])
+    print('find_types("Point", scope=robot):     ', [path(n) for n in global_module.find_types('Point', scope=robot)])
+    print('find_types("::Point"):                ', [path(n) for n in global_module.find_types('::Point')])
+    print('find_types("Point") (no scope):       ', sorted(path(n) for n in global_module.find_types('Point')))
+
+
+if __name__ == '__main__':
+    main()

idl_parser-0.3.2/examples/struct_example.py

@@ -0,0 +1,72 @@
+"""Example: read structs and their members.
+
+Shows how to get
+- the structs in a module (``structs``, ``struct_by_name``),
+- each member's name and type (primitive, struct, sequence, array),
+- a member by name (``member_by_name``) and a nested struct's members.
+
+Run::
+
+    python examples/struct_example.py
+"""
+import _path  # noqa: F401  (use the idl_parser of this checkout)
+
+from idl_parser import parser
+
+IDL = '''
+module my_module {
+  struct Time {
+    long sec;
+    long nsec;
+  };
+
+  struct Pose {
+    double position[3];
+    double orientation[4];
+  };
+
+  struct Odometry {
+    Time stamp;
+    string frame_id;
+    Pose pose;
+    sequence<double> covariance;
+  };
+};
+'''
+
+
+def describe_type(t):
+    """Return a short description of a member type."""
+    if t.is_primitive:
+        return t.name
+    if t.is_sequence:
+        return 'sequence of %s' % t.inner_type.name
+    if t.is_array:
+        return 'array %s' % t.name
+    if t.is_struct:
+        return 'struct %s' % t.full_path
+    return t.name
+
+
+def main():
+    global_module = parser.IDLParser().load(IDL)
+    my_module = global_module.module_by_name('my_module')
+
+    print('structs in my_module:', [s.name for s in my_module.structs])
+    print()
+
+    for struct in my_module.structs:
+        print('struct %s' % struct.full_path)
+        for m in struct.members:
+            print('  %-12s %s' % (m.name, describe_type(m.type)))
+        print()
+
+    odometry = my_module.struct_by_name('Odometry')
+
+    # A member whose type is a struct: follow it to read its members.
+    stamp = odometry.member_by_name('stamp')
+    print('Odometry.stamp members:', [(m.name, m.type.name) for m in stamp.type.members])
+
+
+if __name__ == '__main__':
+    main()

idl_parser-0.3.2/idl_parser/__init__.py

@@ -0,0 +1,18 @@
+"""OMG IDL parser.
+
+Parse IDL files (or IDL text) into a tree of definition objects::
+
+    from idl_parser import parser
+    global_module = parser.IDLParser().load(idl_text)
+    my_module = global_module.module_by_name('my_module')
+
+Start from :class:`idl_parser.parser.IDLParser`; the result is an
+:class:`idl_parser.module.IDLModule` holding the global scope.
+"""
+#from parser import IDLParser
+__all__=['parser', 'exception']
+
+
+
+    
+    

{idl_parser-0.2.2 → idl_parser-0.3.2}/idl_parser/bitmask.py

@@ -46,12 +46,15 @@ class IDLBitValue(node.IDLNode):
 
     @property
     def full_path(self):
+        """Scoped name (``'M::Flags::FLAG_A'``)."""
         return self.parent.full_path + sep + self.name
 
     def to_simple_dic(self):
+        """A compact summary: ``{name: position}``."""
         return {self.name: self.position}
 
     def to_dic(self):
+        """The value as a plain dict (for JSON or YAML output)."""
         return self._with_annotations({'name': self.name,
                 'classname': self.classname,
                 'position': self.position,
@@ -59,7 +62,15 @@ class IDLBitValue(node.IDLNode):
 
 
 class IDLBitmask(node.IDLNode):
-
+    """A ``bitmask`` and its values.
+
+    :param name: Bitmask name.
+    :param parent: Enclosing :class:`~idl_parser.module.IDLModule`.
+    :param annotations: Annotations written before the bitmask; ``@bit_bound``
+        sets :attr:`bit_bound`.
+    :raises ~idl_parser.exception.InvalidIDLSyntaxError: ``@bit_bound`` is not
+        in 1..64.
+    """
     def __init__(self, name, parent, annotations=None):
         super(IDLBitmask, self).__init__('IDLBitmask', name, parent)
         self._verbose = False
@@ -80,6 +91,7 @@ class IDLBitmask(node.IDLNode):
 
     @property
     def full_path(self):
+        """Scoped name (``'M::Flags'``; ``'::Flags'`` at the global scope)."""
         return self.parent.full_path + sep + self.name
 
     @property
@@ -93,12 +105,19 @@ class IDLBitmask(node.IDLNode):
         return self._values
 
     def value_by_name(self, name):
+        """The value named ``name`` (an :class:`IDLBitValue`), or None."""
         for v in self._values:
             if v.name == name:
                 return v
         return None
 
     def to_simple_dic(self, quiet=False, full_path=False, recursive=False, member_only=False):
+        """A compact summary: ``{'bitmask NAME': [{name: position}, ...]}``.
+
+        :param quiet: Return only ``'bitmask NAME'``.
+        :param full_path: Use :attr:`full_path` as the name.
+        :param member_only: Return only the list of value summaries.
+        """
         name = self.full_path if full_path else self.name
         if quiet:
             return 'bitmask %s' % name
@@ -107,6 +126,7 @@ class IDLBitmask(node.IDLNode):
         return {'bitmask %s' % name: [v.to_simple_dic() for v in self.values]}
 
     def to_dic(self):
+        """The bitmask as a plain dict (for JSON or YAML output)."""
         return self._with_annotations({'name': self.name,
                 'filepath': self.filepath,
                 'classname': self.classname,
@@ -114,6 +134,11 @@ class IDLBitmask(node.IDLNode):
                 'values': [v.to_dic() for v in self.values]})
 
     def parse_tokens(self, token_buf, filepath=None):
+        """Parse the bitmask from ``token_buf``, starting after its name, up to ``};``.
+
+        :raises ~idl_parser.exception.InvalidIDLSyntaxError: The declaration is
+            not valid IDL, or a position is out of :attr:`bit_bound` or used twice.
+        """
         self._filepath = filepath
         ln, fn, token = token_buf.pop()
         if token != '{':