py-api-dumper 4.1.1__tar.gz → 4.2.0__tar.gz

{py_api_dumper-4.1.1/src/py_api_dumper.egg-info → py_api_dumper-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-api-dumper
-Version: 4.1.1
+Version: 4.2.0
 Summary: Python API dumping and comparison tool
 Author-email: Karl Wette <karl.wette@anu.edu.au>
 License-Expression: MIT
@@ -77,6 +77,29 @@ $ py-api-dumper --help
   * API entries which have been *added*, i.e. present in the new API but not in
     the old API (e.g. the `b` argument in the above example).
 
+* To filter out undesired entries from API dumps before comparison:
+  ```
+  $ py-api-dumper diff mymod-old.dump mymod-new.dump -i <filter>
+  ```
+  Given the following API:
+  ```
+  MODULE : mymod
+      CLASS : myclass
+          FUNCTION : __init__ : no-return-type
+              REQUIRED : 0 : x : int
+  ```
+  the following filters would ignore the given entries:
+  | `<filter>`                   | Ignore entries                             |
+  | ---------------------------- | ------------------------------------------ |
+  | `MODULE`                     | All modules                                |
+  | `MODULE:mymod`               | All modules named `mymod`                  |
+  | `CLASS`                      | All classes                                |
+  | `CLASS:myclass`              | All classes named `myclass`                |
+  | `MODULE:mymod;CLASS`         | All classes in modules named `mymod`       |
+  | `MODULE:mymod;CLASS:myclass` | Class `myclass` in module `mymod`          |
+  | `FUNCTION:__init__`          | All functions named `__init__`             |
+  | `CLASS;FUNCTION:__init__`    | All functioned named `__init__` in classes |
+
 ## Python interface
 
 ```python
@@ -101,3 +124,9 @@ from py_api_dumper import APIDump, APIDiff
   diff.print_as_text()
   diff.save_as_json("mymod.diff")
   ```
+
+* To filter out undesired entries from API dumps before comparison:
+  ```python
+  filter = APIFilter(("CLASS", "myclass"))   # OR: APIFilter.from_str("CLASS:myclass")
+  diff = APIDiff.from_files("mymod-old.dump", "mymod-new.dump", filter)
+  ```

{py_api_dumper-4.1.1 → py_api_dumper-4.2.0}/README.md

@@ -61,6 +61,29 @@ $ py-api-dumper --help
   * API entries which have been *added*, i.e. present in the new API but not in
     the old API (e.g. the `b` argument in the above example).
 
+* To filter out undesired entries from API dumps before comparison:
+  ```
+  $ py-api-dumper diff mymod-old.dump mymod-new.dump -i <filter>
+  ```
+  Given the following API:
+  ```
+  MODULE : mymod
+      CLASS : myclass
+          FUNCTION : __init__ : no-return-type
+              REQUIRED : 0 : x : int
+  ```
+  the following filters would ignore the given entries:
+  | `<filter>`                   | Ignore entries                             |
+  | ---------------------------- | ------------------------------------------ |
+  | `MODULE`                     | All modules                                |
+  | `MODULE:mymod`               | All modules named `mymod`                  |
+  | `CLASS`                      | All classes                                |
+  | `CLASS:myclass`              | All classes named `myclass`                |
+  | `MODULE:mymod;CLASS`         | All classes in modules named `mymod`       |
+  | `MODULE:mymod;CLASS:myclass` | Class `myclass` in module `mymod`          |
+  | `FUNCTION:__init__`          | All functions named `__init__`             |
+  | `CLASS;FUNCTION:__init__`    | All functioned named `__init__` in classes |
+
 ## Python interface
 
 ```python
@@ -85,3 +108,9 @@ from py_api_dumper import APIDump, APIDiff
   diff.print_as_text()
   diff.save_as_json("mymod.diff")
   ```
+
+* To filter out undesired entries from API dumps before comparison:
+  ```python
+  filter = APIFilter(("CLASS", "myclass"))   # OR: APIFilter.from_str("CLASS:myclass")
+  diff = APIDiff.from_files("mymod-old.dump", "mymod-new.dump", filter)
+  ```

{py_api_dumper-4.1.1 → py_api_dumper-4.2.0}/pyproject.toml

@@ -54,6 +54,7 @@ skip-checking-raises = true
 
 [tool.pytest.ini_options]
 minversion = "6.0"
+pythonpath = ["src"]
 addopts = "--cov=py_api_dumper --cov-report=term-missing --cov-fail-under=100"
 testpaths = ["test"]
 

{py_api_dumper-4.1.1 → py_api_dumper-4.2.0}/src/py_api_dumper/__init__.py

@@ -30,9 +30,85 @@ from typing import (
 )
 
 __author__ = "Karl Wette"
-__version__ = "4.1.1"
+__version__ = "4.2.0"
 
+APIFilterType = TypeVar("APIFilterType", bound="APIFilter")
 APIDumpType = TypeVar("APIDumpType", bound="APIDump")
+APIDiffType = TypeVar("APIDiffType", bound="APIDiff")
+
+
+class APIFilter:
+    """Filter out API entries before comparing API dumps."""
+
+    def __init__(self, *patt: tuple):
+        """API entry filter.
+
+        Args:
+            *patt (tuple): Partial tuples to match to API entry.
+        """
+        self._patt = patt
+
+    @classmethod
+    def from_str(cls: Type[APIFilterType], filter_str: str) -> APIFilterType:
+        """Create an API filter from a string.
+
+        Args:
+            filter_str (str):
+                String to parse into filter.
+
+        Returns:
+            APIFilterType: APIFilter instance.
+        """
+
+        def _to_int_or_str(c):
+            try:
+                return int(c)
+            except ValueError:
+                return c
+
+        return cls(
+            *tuple(
+                tuple(_to_int_or_str(c) for c in s.split(":"))
+                for s in filter_str.split(";")
+            )
+        )
+
+    def match(self, entry: tuple) -> bool:
+        """Return if the API filter matches the given entry.
+
+        Args:
+            entry (tuple):
+                API entry to match.
+
+        Returns:
+            bool: True for a match, False otherwise.
+        """
+
+        # Match fails if pattern is longer than entry
+        if len(self._patt) > len(entry):
+            return False
+
+        # Shift filter pattern across entry
+        for i in range(len(entry) - len(self._patt) + 1):
+
+            # Assume found unless determined otherwise
+            found = True
+            for j in range(len(self._patt)):
+
+                # Match fails if pattern element is longer than entry element
+                if len(self._patt[j]) > len(entry[i + j]):
+                    found = False
+                    break
+
+                # Match fails if first entry elements do not match patterm
+                if entry[i + j][0 : len(self._patt[j])] != self._patt[j]:
+                    found = False
+                    break
+
+            if found:
+                return True
+
+        return False
 
 
 class APIDump:
@@ -408,8 +484,24 @@ class APIDump:
 
         return inst
 
+    def apply_ignore_filter(self, ignore_filters: List[APIFilterType]) -> "APIDump":
+        """Remove API entries that match filters.
 
-APIDiffType = TypeVar("APIDiffType", bound="APIDiff")
+        Args:
+            ignore_filters (List[APIFilterType]):
+                List of filters to apply.
+
+        Returns:
+            APIDump: filtered APIDump instance.
+        """
+
+        filtered_api = self._api
+        for f in ignore_filters:
+            filtered_api = set(e for e in filtered_api if not f.match(e))
+
+        return self.__class__(
+            dump_file=self.dump_file, modules=self.modules, api=filtered_api
+        )
 
 
 class APIDiff:
@@ -470,6 +562,7 @@ class APIDiff:
         cls: Type[APIDiffType],
         old_dump_file: Union[Path, str],
         new_dump_file: Union[Path, str],
+        ignore_filters: Optional[List[APIFilterType]] = None,
     ) -> APIDiffType:
         """Differences between two Python public API dumps loaded from files.
 
@@ -478,6 +571,8 @@ class APIDiff:
                 Name of file containing dump of the old public API.
             new_dump_file (Union[Path, str]):
                 Name of file containing dump of the new public API.
+            ignore_filters (Optional[List[APIFilterType]]):
+                Remove API entries that match filters.
 
         Returns:
             APIDiffType: APIDiff instance.
@@ -487,6 +582,11 @@ class APIDiff:
         old = APIDump.load_from_file(old_dump_file)
         new = APIDump.load_from_file(new_dump_file)
 
+        # Apply filters
+        if ignore_filters and len(ignore_filters) > 0:
+            old = old.apply_ignore_filter(ignore_filters)
+            new = new.apply_ignore_filter(ignore_filters)
+
         # Create instance
         inst = cls(old, new)
 

{py_api_dumper-4.1.1 → py_api_dumper-4.2.0}/src/py_api_dumper/cli.py

@@ -8,7 +8,7 @@ import argparse
 import sys
 from pathlib import Path
 
-from . import APIDiff, APIDump
+from . import APIDiff, APIDump, APIFilter
 
 
 def _dump(args):
@@ -35,7 +35,7 @@ def _dump(args):
 def _diff(args):
 
     # Load API diff
-    diff = APIDiff.from_files(args.old_dump, args.new_dump)
+    diff = APIDiff.from_files(args.old_dump, args.new_dump, args.ignore)
 
     if args.output is None:
 
@@ -84,6 +84,13 @@ def cli(*argv):
     parser_diff.add_argument(
         "-t", "--text", action="store_true", help="Output API diff in text format"
     )
+    parser_diff.add_argument(
+        "-i",
+        "--ignore",
+        action="append",
+        type=APIFilter.from_str,
+        help="Use filter to ignore API dump entries before comparison",
+    )
     parser_diff.add_argument(
         "old_dump", type=Path, help="File containing dump of old API"
     )

{py_api_dumper-4.1.1 → py_api_dumper-4.2.0/src/py_api_dumper.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-api-dumper
-Version: 4.1.1
+Version: 4.2.0
 Summary: Python API dumping and comparison tool
 Author-email: Karl Wette <karl.wette@anu.edu.au>
 License-Expression: MIT
@@ -77,6 +77,29 @@ $ py-api-dumper --help
   * API entries which have been *added*, i.e. present in the new API but not in
     the old API (e.g. the `b` argument in the above example).
 
+* To filter out undesired entries from API dumps before comparison:
+  ```
+  $ py-api-dumper diff mymod-old.dump mymod-new.dump -i <filter>
+  ```
+  Given the following API:
+  ```
+  MODULE : mymod
+      CLASS : myclass
+          FUNCTION : __init__ : no-return-type
+              REQUIRED : 0 : x : int
+  ```
+  the following filters would ignore the given entries:
+  | `<filter>`                   | Ignore entries                             |
+  | ---------------------------- | ------------------------------------------ |
+  | `MODULE`                     | All modules                                |
+  | `MODULE:mymod`               | All modules named `mymod`                  |
+  | `CLASS`                      | All classes                                |
+  | `CLASS:myclass`              | All classes named `myclass`                |
+  | `MODULE:mymod;CLASS`         | All classes in modules named `mymod`       |
+  | `MODULE:mymod;CLASS:myclass` | Class `myclass` in module `mymod`          |
+  | `FUNCTION:__init__`          | All functions named `__init__`             |
+  | `CLASS;FUNCTION:__init__`    | All functioned named `__init__` in classes |
+
 ## Python interface
 
 ```python
@@ -101,3 +124,9 @@ from py_api_dumper import APIDump, APIDiff
   diff.print_as_text()
   diff.save_as_json("mymod.diff")
   ```
+
+* To filter out undesired entries from API dumps before comparison:
+  ```python
+  filter = APIFilter(("CLASS", "myclass"))   # OR: APIFilter.from_str("CLASS:myclass")
+  diff = APIDiff.from_files("mymod-old.dump", "mymod-new.dump", filter)
+  ```

{py_api_dumper-4.1.1 → py_api_dumper-4.2.0}/test/test_diff.py

@@ -12,7 +12,7 @@ from pathlib import Path
 import api_ref
 import pytest
 
-from py_api_dumper import APIDiff, APIDump
+from py_api_dumper import APIDiff, APIDump, APIFilter
 from py_api_dumper.cli import cli
 
 
@@ -387,3 +387,12 @@ def test_diff_cli_json(api_dump_file, api_dump_new_file, request):
     assert api_diff.added == set(
         tuple(tuple(e) for e in entry) for entry in api_diff_json["added"]
     )
+
+
+def test_diff_ignore_filter(api_dump_file, api_dump_new_file, request):
+    """Test comparing API dumps with ignore filter."""
+    api_diff = APIDiff.from_files(
+        api_dump_file, api_dump_new_file, [APIFilter.from_str("CLASS:C1")]
+    )
+    assert len(api_diff.removed) == 4
+    assert len(api_diff.added) == 10

{py_api_dumper-4.1.1 → py_api_dumper-4.2.0}/test/test_dump.py

@@ -9,7 +9,7 @@ from pathlib import Path
 import api_ref
 import pytest
 
-from py_api_dumper import APIDump
+from py_api_dumper import APIDump, APIFilter
 from py_api_dumper.cli import cli
 
 
@@ -46,6 +46,39 @@ def test_dump_module_cli(request):
     _compare_dumps(api_dump_text)
 
 
+@pytest.mark.parametrize(
+    "patt,n_filtered_entries",
+    [
+        [[("MEMBER", "d1")], 1],
+        [[("CLASS", "C1"), ("MEMBER", "f1")], 1],
+        [[("CLASS", "C1")], 35],
+        [[("MEMBER", "does-not-exist", "just-to-test", "long-filter")], 0],
+    ],
+)
+def test_dump_module_filter(request, patt, n_filtered_entries):
+    """Create API dump from module and apply filter."""
+    api_dump = APIDump.from_modules(api_ref)
+    n_api_entries_before = len(api_dump._api)
+    api_dump = api_dump.apply_ignore_filter([APIFilter(*patt)])
+    assert len(api_dump._api) == n_api_entries_before - n_filtered_entries
+
+
+@pytest.mark.parametrize(
+    "filter_str,n_filtered_entries",
+    [
+        ["MEMBER:d1", 1],
+        ["CLASS:C1;MEMBER:f1", 1],
+        ["CLASS:C1", 35],
+    ],
+)
+def test_dump_module_filter_str(request, filter_str, n_filtered_entries):
+    """Create API dump from module and apply filter created from string."""
+    api_dump = APIDump.from_modules(api_ref)
+    n_api_entries_before = len(api_dump._api)
+    api_dump = api_dump.apply_ignore_filter([APIFilter.from_str(filter_str)])
+    assert len(api_dump._api) == n_api_entries_before - n_filtered_entries
+
+
 def test_dump_file(request):
     """Test save and loading API dumps."""
     api_dump = APIDump.from_modules(api_ref)