py-api-dumper 1.0__tar.gz

py_api_dumper-1.0/LICENSE

@@ -0,0 +1,18 @@
+Copyright 2025 Karl Wette
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

py_api_dumper-1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+prune test
+include test/*.py
+include test/api_ref/*.c
+include test/api_ref/*.py
+include test/api_ref/*.txt

py_api_dumper-1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: py-api-dumper
+Version: 1.0
+Summary: Python API dumping and comparison tool
+Author-email: Karl Wette <karl.wette@anu.edu.au>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kwwette/py-api-dumper
+Project-URL: Issues, https://github.com/kwwette/py-api-dumper/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Python API dumping and comparison tool
+
+Dumps the public API of a Python module and its members to a file, which can
+then be used to show the differences in the public between two dumps, e.g. of
+different versions of the same module.
+
+## Command-line interface
+
+* To dump the public API of a module `mymod`:
+
+  ```bash
+  $ py-api-dumper dump -o mymod1.dump mymod
+  ```
+
+  `mymod1.dump` will record the public API of `mymod` in a reloadable format.
+
+* To print the API of `mymod` in text format:
+  ```bash
+  $ py-api-dumper dump mymod
+  MODULE : mymod
+      CLASS : myclass
+          FUNCTION : __init__ : no-return-type
+              REQUIRED : 0 : x : int
+  ...
+  ```
+
+  The text format is a tree of entries of each nested class, class method,
+  function, member variable, etc. in the public API.
+
+* To compare the API of `mymod` between different versions:
+  ```bash
+  $ py-api-dumper diff mymod-old.dump mymod-new.dump
+  --- mymod-old.dump mymod=1.0
+  +++ mymod-new.dump mymod=2.0
+  +MODULE : mymod
+  +    CLASS : myclass
+  +        FUNCTION : __init__ : no-return-type
+  +            REQUIRED : 1 : b : no-type
+  ```
+
+  The above output shows the expected output if, between `mymod` versions 1.0
+  and 2.0, an additional positional argument `b` had been added to the
+  `__init__` method of the class `mymod.myclass`.
+
+  ```bash
+  $ py-api-dumper diff -o mymod.diff ...
+  ```
+
+  This will write out the API differences to `mymod.diff`  in JSON format:
+
+  * the paths to the dumps of the old and new APIs, e.g. `mymod-old.dump`
+    vs. `mymod-new.dump`;
+  * the version of `mymod` at the old and new API dumps, e.g. mymod `1.0`
+    vs. `2.0`;
+  * API entries which have been *removed*, i.e. present in the old API but not
+    in the new API (e.g. none in the above example);
+  * 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).
+
+## Python interface
+
+```python
+from py_api_dumper import APIDump, APIDiff
+```
+
+* To dump the public API of a module `mymod`:
+  ```python
+  import mymod
+  dump = APIDump.from_modules(mymod)   # OR: APIDump.from_modules("mymod")
+  dump.save_to_file("mymod.dump")
+  ```
+
+* To print the API of `mymod` in text format:
+  ```python
+  dump.print_as_text()
+  ```
+
+* To compare the API of `mymod` between different versions:
+  ```python
+  diff = APIDiff.from_files("mymod-old.dump", "mymod-new.dump")
+  diff.print_as_text()
+  with open("mymod.diff", as file):
+        diff.print_as_json(file)
+  ```

py_api_dumper-1.0/README.md

@@ -0,0 +1,84 @@
+# Python API dumping and comparison tool
+
+Dumps the public API of a Python module and its members to a file, which can
+then be used to show the differences in the public between two dumps, e.g. of
+different versions of the same module.
+
+## Command-line interface
+
+* To dump the public API of a module `mymod`:
+
+  ```bash
+  $ py-api-dumper dump -o mymod1.dump mymod
+  ```
+
+  `mymod1.dump` will record the public API of `mymod` in a reloadable format.
+
+* To print the API of `mymod` in text format:
+  ```bash
+  $ py-api-dumper dump mymod
+  MODULE : mymod
+      CLASS : myclass
+          FUNCTION : __init__ : no-return-type
+              REQUIRED : 0 : x : int
+  ...
+  ```
+
+  The text format is a tree of entries of each nested class, class method,
+  function, member variable, etc. in the public API.
+
+* To compare the API of `mymod` between different versions:
+  ```bash
+  $ py-api-dumper diff mymod-old.dump mymod-new.dump
+  --- mymod-old.dump mymod=1.0
+  +++ mymod-new.dump mymod=2.0
+  +MODULE : mymod
+  +    CLASS : myclass
+  +        FUNCTION : __init__ : no-return-type
+  +            REQUIRED : 1 : b : no-type
+  ```
+
+  The above output shows the expected output if, between `mymod` versions 1.0
+  and 2.0, an additional positional argument `b` had been added to the
+  `__init__` method of the class `mymod.myclass`.
+
+  ```bash
+  $ py-api-dumper diff -o mymod.diff ...
+  ```
+
+  This will write out the API differences to `mymod.diff`  in JSON format:
+
+  * the paths to the dumps of the old and new APIs, e.g. `mymod-old.dump`
+    vs. `mymod-new.dump`;
+  * the version of `mymod` at the old and new API dumps, e.g. mymod `1.0`
+    vs. `2.0`;
+  * API entries which have been *removed*, i.e. present in the old API but not
+    in the new API (e.g. none in the above example);
+  * 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).
+
+## Python interface
+
+```python
+from py_api_dumper import APIDump, APIDiff
+```
+
+* To dump the public API of a module `mymod`:
+  ```python
+  import mymod
+  dump = APIDump.from_modules(mymod)   # OR: APIDump.from_modules("mymod")
+  dump.save_to_file("mymod.dump")
+  ```
+
+* To print the API of `mymod` in text format:
+  ```python
+  dump.print_as_text()
+  ```
+
+* To compare the API of `mymod` between different versions:
+  ```python
+  diff = APIDiff.from_files("mymod-old.dump", "mymod-new.dump")
+  diff.print_as_text()
+  with open("mymod.diff", as file):
+        diff.print_as_json(file)
+  ```

py_api_dumper-1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "py-api-dumper"
+version = "1.0"
+description = "Python API dumping and comparison tool"
+authors = [
+    { name = "Karl Wette", email = "karl.wette@anu.edu.au" },
+]
+requires-python = ">=3.9"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/kwwette/py-api-dumper"
+Issues = "https://github.com/kwwette/py-api-dumper/issues"
+
+[project.scripts]
+py-api-dumper = "py_api_dumper.cli:cli"
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "--cov=py_api_dumper --cov-report=term-missing --cov-fail-under=100"
+testpaths = ["test"]

py_api_dumper-1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_api_dumper-1.0/src/py_api_dumper/__init__.py

@@ -0,0 +1,418 @@
+import importlib
+import importlib.metadata
+import inspect
+import json
+import pkgutil
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import List, Optional, TextIO, Tuple, Type, TypeVar, Union
+
+__author__ = "Karl Wette"
+__version__ = "1.0"
+
+APIDumpType = TypeVar("APIDumpType", bound="APIDump")
+
+
+class APIDump:
+    """
+    Dump the public API of a Python module and its members.
+    """
+
+    def __init__(self, *, api, versions, file_path=None):
+        self._api = api
+        self._versions = versions
+        self._file_path = file_path
+
+    def __eq__(self, other):
+        return self._api == other._api and self._versions == other._versions
+
+    @classmethod
+    def from_modules(
+        cls: Type[APIDumpType], *modules: Union[ModuleType, str]
+    ) -> APIDumpType:
+        """
+        Dump the public API of the given Python modules.
+
+        Args:
+            *modules (Union[ModuleType, str]):
+                List of modules and/or their string names.
+
+        Returns:
+            APIDumpType: APIDump instance.
+        """
+
+        # Create instance
+        inst = cls(api=set(), versions=dict())
+
+        # Load all modules
+        all_modules = inst._load_all_modules(modules)
+
+        # Dump module APIs
+        for module in all_modules:
+            module_prefix = [("MODULE", m) for m in module.__name__.split(".")]
+            inst._dump_struct(module_prefix, module, module)
+
+        return inst
+
+    def _load_all_modules(self, modules):
+
+        # Walk and load (sub)modules
+        all_modules = dict()
+        for module_or_name in modules:
+
+            # Load module if supplied a string name
+            if isinstance(module_or_name, ModuleType):
+                module = module_or_name
+            else:
+                module = importlib.import_module(module_or_name)
+
+            # Save module
+            if module.__name__ not in all_modules:
+                all_modules[module.__name__] = module
+
+            # Save module version
+            try:
+                module_version = importlib.metadata.version(module.__name__)
+            except importlib.metadata.PackageNotFoundError:
+                try:
+                    module_version = module.__version__
+                except AttributeError:
+                    module_version = None
+            self._versions[module.__name__] = module_version
+
+            # Walk submodules
+            for submodule_info in pkgutil.walk_packages(
+                module.__path__, module.__name__ + "."
+            ):
+
+                # Exclude private submodules
+                if any(m.startswith("_") for m in submodule_info.name.split(".")):
+                    continue
+
+                # Load submodule
+                submodule = importlib.import_module(submodule_info.name)
+
+                # Save submodule
+                if submodule.__name__ not in all_modules:
+                    all_modules[submodule.__name__] = submodule
+
+        return list(all_modules.values())
+
+    def _add_api_entry(self, entry):
+
+        # Check that `entry` only contains `str` or `int` values
+        _allowed_types = (str, int)
+        assert all(
+            all(isinstance(e, _allowed_types) for e in ee) for ee in entry
+        ), tuple(tuple((e, isinstance(e, _allowed_types)) for e in ee) for ee in entry)
+
+        # Add API entry
+        self._api.add(tuple(entry))
+
+    def _dump_struct(self, prefix, struct, module):
+
+        # Add base entry
+        self._add_api_entry(prefix)
+
+        # Iterate over struct members
+        members = inspect.getmembers(struct)
+        for member_name, member in members:
+
+            # Exclude any modules
+            # - all relevant modules have already been found by _load_all_modules()
+            if inspect.ismodule(member):
+                continue
+
+            # Exclude any private members, except class constructors
+            if member_name.startswith("_") and member_name != "__init__":
+                continue
+
+            # Exclude any members defined in another module
+            # - this should catch any `import`ed members
+            if hasattr(member, "__module__") and member.__module__ != module.__name__:
+                continue
+
+            # Dump classes
+            if inspect.isclass(member):
+                class_prefix = prefix + [("CLASS", member.__name__)]
+                self._dump_struct(class_prefix, member, module)
+
+            # Dump methods and functions
+            elif inspect.isroutine(member):
+                if isinstance(
+                    inspect.getattr_static(struct, member.__name__), staticmethod
+                ):
+                    self._dump_function(prefix, "STATICMETHOD", member)
+                if inspect.ismethod(member) and isinstance(member.__self__, type):
+                    self._dump_function(prefix, "CLASSMETHOD", member)
+                else:
+                    self._dump_function(prefix, "FUNCTION", member)
+
+            # Dump properties
+            elif isinstance(member, property) or inspect.isgetsetdescriptor(member):
+                self._dump_property(prefix, member_name)
+
+            else:
+                # Dump everything else
+                self._dump_member(prefix, member_name, member)
+
+    def _dump_function(self, prefix, fun_type, fun):
+
+        # Try to get function signature
+        try:
+            sig = inspect.signature(fun)
+        except ValueError:
+            sig = None
+
+        # Add function entry
+        if sig is not None:
+            if sig.return_annotation != sig.empty:
+                return_type = str(sig.return_annotation)
+            else:
+                return_type = "no-return-type"
+            func_entry = prefix + [(fun_type, fun.__name__, return_type)]
+        else:
+            func_entry = prefix + [(fun_type, fun.__name__, "no-signature")]
+        self._add_api_entry(func_entry)
+
+        # Add function signature, if available
+        if sig is not None:
+            n_req_arg = 0
+            for n, par in enumerate(sig.parameters.values()):
+                if par.annotation != par.empty:
+                    par_type = str(par.annotation)
+                else:
+                    par_type = "no-type"
+                if par.default != par.empty or par.kind in (
+                    par.VAR_POSITIONAL,
+                    par.VAR_KEYWORD,
+                ):
+                    par_entry = [("OPTIONAL", par.name, par_type)]
+                else:
+                    par_entry = [("REQUIRED", n_req_arg, par.name, par_type)]
+                    n_req_arg += 1
+                self._add_api_entry(func_entry + par_entry)
+
+    def _dump_property(self, prefix, name):
+
+        # Add property entry
+        entry = prefix + [("PROPERTY", name)]
+        self._add_api_entry(entry)
+
+    def _dump_member(self, prefix, name, val):
+
+        # Exclude any private types
+        typ = type(val).__name__
+        if typ.startswith("_"):
+            return
+
+        # Add member entry
+        entry = prefix + [("MEMBER", name, typ)]
+        self._add_api_entry(entry)
+
+    def print_as_text(self, file: Optional[TextIO] = None) -> None:
+        """
+        Print the API dump as text to a file.
+
+        Args:
+            file (Optional[TextIO]):
+                File to print to (default: standard output).
+        """
+        if file is None:
+            file = sys.stdout
+
+        # Print API dump
+        for entry in sorted(self._api):
+            indent = "\t" * (len(entry) - 1)
+            entry_str = " : ".join(str(e) for e in entry[-1])
+            print(indent + entry_str, file=file)
+
+    def save_to_file(self, file_path: Union[Path, str]) -> None:
+        """
+        Save the API dump to a file in a reloadable format.
+
+        Args:
+            file_path (Union[Path, str]):
+                Name of file to save to.
+        """
+        file_path = Path(file_path)
+
+        # Assemble file content
+        content = {"versions": self._versions, "api": list(sorted(self._api))}
+
+        # Save to file as JSON
+        with file_path.open("wt") as file:
+            json.dump(content, file)
+            file.write("\n")
+
+    @classmethod
+    def load_from_file(
+        cls: Type[APIDumpType], file_path: Union[Path, str]
+    ) -> APIDumpType:
+        """
+        Load an API dump from a file.
+
+        Args:
+            file_path (Union[Path, str]):
+                Name of file to load.
+
+        Returns:
+            APIDumpType: APIDump instance.
+        """
+        file_path = Path(file_path)
+
+        # Load from file as JSON
+        with file_path.open("rt") as file:
+            content = json.load(file)
+
+        # Create instance
+        inst = cls(
+            api=set(tuple(tuple(e) for e in entry) for entry in content["api"]),
+            versions=dict(
+                (module, version) for module, version in content["versions"].items()
+            ),
+            file_path=file_path,
+        )
+
+        return inst
+
+
+APIDiffType = TypeVar("APIDiffType", bound="APIDiff")
+
+
+class APIDiff:
+    """
+    Show the differences between two Python public API dumps.
+    """
+
+    def __init__(
+        self,
+        old: APIDump,
+        new: APIDump,
+    ):
+        """
+        Differences between two Python public API dumps.
+
+        Args:
+            old (APIDump):
+                Dump of the old public API.
+            new (APIDump):
+                Dump of the new public API.
+        """
+
+        self._old_versions = old._versions
+        self._old_path = old._file_path
+
+        self._new_versions = new._versions
+        self._new_path = new._file_path
+
+        # Entries added to `new` that are not in `old`
+        self._added = new._api - old._api
+
+        # Entries removed from `new` that remain in `old`
+        self._removed = old._api - new._api
+
+    @classmethod
+    def from_files(
+        cls: Type[APIDiffType], old_path: Union[Path, str], new_path: Union[Path, str]
+    ) -> APIDiffType:
+        """
+        Differences between two Python public API dumps loaded from files.
+
+        Args:
+            old_path (Union[Path, str]):
+                Name of file containing dump of the old public API.
+            new_path (Union[Path, str]):
+                Name of file containing dump of the new public API.
+
+        Returns:
+            APIDiffType: APIDiff instance.
+        """
+
+        # Load dumps from files
+        old = APIDump.load_from_file(old_path)
+        new = APIDump.load_from_file(new_path)
+
+        # Create instance
+        inst = cls(old, new)
+
+        return inst
+
+    def equal(self):
+        """
+        Return True if there are no differences, False otherwise.
+        """
+        return len(self._added) == 0 and len(self._removed) == 0
+
+    def print_as_text(self, file: Optional[TextIO] = None) -> None:
+        """
+        Print the API differences as text to a file.
+
+        Args:
+            file (Optional[TextIO]):
+                File to print to (default: standard output).
+        """
+        file = file or sys.stdout
+
+        # Print file names and versions
+        for prefix, file_path, versions in (
+            ("---", self._old_path, self._old_versions),
+            ("+++", self._new_path, self._new_versions),
+        ):
+            print(
+                prefix,
+                "/dev/null" if file_path is None else str(file_path),
+                " ".join(
+                    f"{module}={version}"
+                    for module, version in versions.items()
+                    if version is not None
+                ),
+                file=file,
+            )
+
+        # Print API entries added and removed
+        for prefix, entries in (("-", self._removed), ("+", self._added)):
+            stack: List[Tuple] = []
+            for entry in sorted(entries):
+
+                # Find the longest common prefix with respect to previously-printed entries
+                i_start = 0
+                while len(stack) > 0:
+                    for i in range(max(len(stack[-1]), len(entry))):
+                        if stack[-1][0:i] == entry[0:i]:
+                            i_start = i
+                    if i_start > 0:
+                        break
+                    stack.pop()  # pragma: no cover
+
+                # Print entry without common prefix; add to stack of printed entries
+                for i in range(i_start, len(entry)):
+                    indent = "\t" * i
+                    entry_str = " : ".join(str(e) for e in entry[i])
+                    print(prefix + indent + entry_str, file=file)
+                stack.append(entry)
+
+    def print_as_json(self, file: Optional[TextIO] = None) -> None:
+        """
+        Print the API differences as JSON to a file.
+
+        Args:
+            file (Optional[TextIO]):
+                File to print to (default: standard output).
+        """
+        file = file or sys.stdout
+
+        # Assemble file content
+        content = {
+            "old_dump": str(self._old_path),
+            "new_dump": str(self._new_path),
+            "old_versions": self._old_versions,
+            "new_versions": self._new_versions,
+            "removed": list(sorted(self._removed)),
+            "added": list(sorted(self._added)),
+        }
+
+        # Save to file as JSON
+        json.dump(content, file)
+        file.write("\n")