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

py_api_dumper-4.2.0/LICENSES/CC0-1.0.txt

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

{py_api_dumper-4.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
+Version: 4.2.0
 Summary: Python API dumping and comparison tool
 Author-email: Karl Wette <karl.wette@anu.edu.au>
 License-Expression: MIT
@@ -11,6 +11,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSES/MIT.txt
+License-File: LICENSES/CC0-1.0.txt
 Dynamic: license-file
 
 # Python API dumping and comparison tool
@@ -76,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
@@ -100,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 → 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 → py_api_dumper-4.2.0}/pyproject.toml

@@ -11,7 +11,7 @@ authors = [
 requires-python = ">=3.10"
 readme = "README.md"
 license = "MIT"
-license-files = ["LICENSES/MIT.txt"]
+license-files = ["LICENSES/MIT.txt", "LICENSES/CC0-1.0.txt"]
 classifiers = [
     "Programming Language :: Python :: 3",
     "Operating System :: OS Independent",
@@ -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 → 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"
+__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 → 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 → 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
+Version: 4.2.0
 Summary: Python API dumping and comparison tool
 Author-email: Karl Wette <karl.wette@anu.edu.au>
 License-Expression: MIT
@@ -11,6 +11,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSES/MIT.txt
+License-File: LICENSES/CC0-1.0.txt
 Dynamic: license-file
 
 # Python API dumping and comparison tool
@@ -76,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
@@ -100,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 → py_api_dumper-4.2.0}/src/py_api_dumper.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 MANIFEST.in
 README.md
 pyproject.toml
+LICENSES/CC0-1.0.txt
 LICENSES/MIT.txt
 src/py_api_dumper/__init__.py
 src/py_api_dumper/cli.py

{py_api_dumper-4.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 → 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)