[cmake_frontend.py] use pathlib instead of os; add documentation

Author: diivm

clang_bind/cmake_frontend.py

@@ -1,27 +1,23 @@
-import os
 import json
 import clang.cindex as clang
+from pathlib import Path
 
 
 class CompilationDatabase:
-    """
-    Build a compilation database from a given directory
-    """
+    """Class to get information from a CMake compilation database."""
 
     def __init__(self, build_dir):
         self.compilation_database = clang.CompilationDatabase.fromDirectory(
             buildDir=build_dir
         )
 
     def get_compilation_arguments(self, filename=None):
-        """
-        Returns the compilation commands extracted from the compilation database
-
-        Parameters:
-            - filename (optional): To get compilaton commands of a file
+        """Returns the compilation commands extracted from the compilation database
 
-        Returns:
-            - compilation_arguments (dict): {filename: compiler arguments}
+        :param filename: Get compilation arguments of the file, defaults to None: get for all files
+        :type filename: str, optional
+        :return: ilenames and their compiler arguments: {filename: compiler arguments}
+        :rtype: dict
         """
 
         if filename:
@@ -40,25 +36,42 @@ def get_compilation_arguments(self, filename=None):
 
 
 class Codemodel:
+    """Class to get information about the Codemodel generated by the CMake file API."""
+
     def __init__(self, reply_dir):
         self.reply_dir = reply_dir
         self.codemodel = {}
         self.codemodel_targets = {}
 
     def set_codemodel(self, codemodel_file=None):
+        """Set the codemodel variable.
+
+        :param codemodel_file: codemodel file to read from, defaults to None
+        :type codemodel_file: str, optional
+        """
         if not codemodel_file:
-            for file in os.listdir(self.reply_dir):
-                if file.startswith("codemodel"):
-                    codemodel_file = os.path.join(self.reply_dir, file)
+            for file in Path(self.reply_dir).iterdir():
+                if file.name.startswith("codemodel"):
+                    codemodel_file = Path(self.reply_dir, file)
         with open(codemodel_file) as f:
             self.codemodel = json.load(f)
 
     def get_codemodel(self):
+        """Get the codemodel.
+
+        :return: JSON codemodel object.
+        :rtype: dict
+        """
         if not self.codemodel:
             self.set_codemodel()
         return self.codemodel
 
     def set_codemodel_targets(self, codemodel=None):
+        """Set targets variable.
+
+        :param codemodel: Codemodel dict object, defaults to None
+        :type codemodel: dict, optional
+        """
         if not codemodel:
             codemodel = self.get_codemodel()
         configurations = codemodel.get("configurations", [])
@@ -68,37 +81,69 @@ def set_codemodel_targets(self, codemodel=None):
                 self.codemodel_targets.update({target["name"]: target["jsonFile"]})
 
     def get_codemodel_targets(self):
+        """Get codemodel targets.
+
+        :return: dict of targets and the corresponding file
+        :rtype: dict
+        """
         if not self.codemodel_targets:
             self.set_codemodel_targets()
         return self.codemodel_targets
 
 
 class Target:
+    """Class to get information about targets found from the CMake file API."""
+
     def __init__(self, reply_dir, target_name):
         self.reply_dir = reply_dir
         self.target_file = Codemodel(reply_dir).get_codemodel_targets().get(target_name)
         self.target = {}
 
     def set_target(self, target_file=None):
+        """Set target variable.
+
+        :param target_file: File to get target from, defaults to None
+        :type target_file: str, optional
+        """
         if not target_file:
             target_file = self.target_file
-        with open(os.path.join(self.reply_dir, target_file)) as f:
+        with open(Path(self.reply_dir, target_file)) as f:
             self.target = json.load(f)
 
     def get_target(self):
+        """Get target.
+
+        :return: JSON target
+        :rtype: dict
+        """
         if not self.target:
             self.set_target()
         return self.target
 
     def get_artifacts(self):
+        """Get artifacts from the target.
+
+        :return: Artifacts' paths
+        :rtype: list
+        """
         return [
             artifact.get("path") for artifact in self.get_target().get("artifacts", [])
         ]
 
     def get_commands(self):
+        """Get commands from the target.
+
+        :return: Commands concerning the build system.
+        :rtype: list
+        """
         return self.get_target().get("backtraceGraph", {}).get("commands")
 
     def get_compile_groups(self):
+        """Get compile groups from the target.
+
+        :return: list of dictionaries of compile groups
+        :rtype: list
+        """
         return [
             {
                 "fragments": [
@@ -119,21 +164,46 @@ def get_compile_groups(self):
         ]
 
     def get_dependencies(self):
+        """Get dependencies from the target.
+
+        :return: Dependencies ids' list
+        :rtype: list
+        """
         return [
             dependency.get("id")
             for dependency in self.get_target().get("dependencies", [])
         ]
 
     def get_files(self):
+        """Get files from the target.
+
+        :return: Files concerning the build system.
+        :rtype: list
+        """
         return self.get_target().get("backtraceGraph", {}).get("files")
 
     def get_folder(self):
+        """Get folder from the target.
+
+        :return: Folder of the target.
+        :rtype: str
+        """
         return self.get_target().get("folder", {}).get("name")
 
     def get_id(self):
+        """Get id from the target.
+
+        :return: ID of the target
+        :rtype: str
+        """
         return self.get_target().get("id")
 
     def get_install(self):
+        """Get install info from the target.
+
+        :return: Install info
+        :rtype: dict
+        """
         install = self.get_target().get("install", {})
         return {
             "destinations": [
@@ -144,6 +214,11 @@ def get_install(self):
         }
 
     def get_link(self):
+        """Get link info from the target.
+
+        :return: Link info
+        :rtype: dict
+        """
         link = self.get_target().get("link", {})
         command_fragments = link.get("commandFragments", [])
         return {
@@ -161,30 +236,64 @@ def get_link(self):
         }
 
     def get_name(self):
+        """Get name from the target.
+
+        :return: Name of the target
+        :rtype: str
+        """
         return self.get_target().get("name")
 
     def get_name_on_disk(self):
+        """Get name on disk from the target.
+
+        :return: Name on disk of the target
+        :rtype: str
+        """
         return self.get_target().get("nameOnDisk")
 
     def get_paths(self):
+        """Get paths from the target.
+
+        :return: Paths of the target.
+        :rtype: dict
+        """
         return self.get_target().get("paths")
 
     def get_sources(self):
+        """Get sources from the target.
+
+        :return: Sources of the target.
+        :rtype: list
+        """
         return [sources.get("path") for sources in self.get_target().get("sources", [])]
 
     def get_type(self):
+        """Get type from the target.
+
+        :return: Type of the target.
+        :rtype: str
+        """
         return self.get_target().get("type")
 
 
 class CMakeFileAPI:
+    """CMake File API front end."""
+
     def __init__(self, build_dir):
-        reply_dir = os.path.join(build_dir, ".cmake", "api", "v1", "reply")
+        reply_dir = Path(build_dir, ".cmake", "api", "v1", "reply")
         self.targets = {}
         for codemodel_target in Codemodel(reply_dir).get_codemodel_targets():
             target = Target(reply_dir, codemodel_target)
             self.targets[target.get_name()] = target
 
     def get_dependencies(self, target=None):
+        """Get dependencies of the target(s).
+
+        :param target: Target to get the dependencies, defaults to None
+        :type target: str, optional
+        :return: Dependencies of the target(s).
+        :rtype: dict
+        """
         targets = [self.targets.get(target)] if target else self.targets.values()
         return {
             target.get_name(): list(
@@ -194,6 +303,12 @@ def get_dependencies(self, target=None):
         }
 
     def get_sources(self, target=None):
+        """Get sources of the target(s).
+
+        :param target: Target to get the dependencies, defaults to None
+        :type target: str, optional
+        :return: Sources of the target(s).
+        :rtype: dict
+        """
         targets = [self.targets.get(target)] if target else self.targets.values()
         return {target.get_name(): target.get_sources() for target in targets}
-