code style improvements

Author: mbdevpl

test/examples.py

@@ -148,6 +148,10 @@ def _remove_version_suffixes(path: pathlib.Path) -> t.Optional[pathlib.Path]:
 
 
 def case_to_version_tuple(args, kwargs):
+    """Convert parameters of a given test case to a version tuple.
+
+    To be converted are args and kwargs meant for Version.__init__().
+    """
     return args + tuple(
         v for _, v in sorted(kwargs.items(), key=lambda _: KWARG_NAMES.index(_[0])))
 

version_query/__main__.py

@@ -1,4 +1,4 @@
-"""Tool for querying current versions of Python packages."""
+"""Entry point of the command-line interface of version_query package."""
 
 from .main import main
 

version_query/git_query.py

@@ -40,6 +40,30 @@ def _git_version_tags(repo: git.Repo) -> t.Mapping[git.Tag, Version]:
     return versions
 
 
+def _latest_git_version_tag_on_branches(
+        repo: git.Repo, assume_if_none: bool, commit: git.Commit, commit_distance: int,
+        skip_commits: t.Set[git.Commit]):
+    _LOG.log(logging.NOTSET, 'entering %i branches...', len(commit.parents))
+    results = []
+    main_commit_distance = None
+    for parent in commit.parents:
+        try:
+            result = _latest_git_version_tag(
+                repo, assume_if_none, parent, commit_distance, skip_commits)
+            if main_commit_distance is None:
+                main_commit_distance = result[3]
+        except ValueError:
+            continue
+        if result[2] is not None:
+            results.append(result)
+    if not results:
+        return main_commit_distance
+    final_result = sorted(results, key=lambda _: _[2])[-1]
+    _LOG.log(logging.NOTSET, 'result from %i branches is %s and %s',
+             len(commit.parents), *final_result[1:3])
+    return final_result
+
+
 MAX_COMMIT_DISTANCE = 999
 
 
@@ -76,31 +100,35 @@ def _latest_git_version_tag(
         commit_distance += 1
         if len(commit.parents) <= 1:
             continue
-        _LOG.log(logging.NOTSET, 'entering %i branches...', len(commit.parents))
-        results = []
-        main_commit_distance = None
-        for parent in commit.parents:
-            try:
-                result = _latest_git_version_tag(
-                    repo, assume_if_none, parent, commit_distance, skip_commits)
-                if main_commit_distance is None:
-                    main_commit_distance = result[3]
-            except ValueError:
-                continue
-            if result[2] is not None:
-                results.append(result)
-        if not results:
-            commit_distance = main_commit_distance
+        result = _latest_git_version_tag_on_branches(
+            repo, assume_if_none, commit, commit_distance, skip_commits)
+        if not isinstance(result, tuple):
+            commit_distance = result  # main_commit_distance
             break
-        result = sorted(results, key=lambda _: _[2])[-1]
-        _LOG.log(logging.NOTSET, 'result from %i branches is %s and %s',
-                 len(commit.parents), *result[1:3])
+        # _LOG.log(logging.NOTSET, 'entering %i branches...', len(commit.parents))
+        # results = []
+        # main_commit_distance = None
+        # for parent in commit.parents:
+        #     try:
+        #         result = _latest_git_version_tag(
+        #             repo, assume_if_none, parent, commit_distance, skip_commits)
+        #         if main_commit_distance is None:
+        #             main_commit_distance = result[3]
+        #     except ValueError:
+        #         continue
+        #     if result[2] is not None:
+        #         results.append(result)
+        # if not results:
+        #     commit_distance = main_commit_distance
+        #     break
+        # result = sorted(results, key=lambda _: _[2])[-1]
+        # _LOG.log(logging.NOTSET, 'result from %i branches is %s and %s',
+        #          len(commit.parents), *result[1:3])
         return result
     if not current_version_tags:
         if assume_if_none:
             return commit, None, Version.from_str('0.1.0.dev0'), commit_distance
-        else:
-            raise ValueError('the given repo {} has no version tags'.format(repo))
+        raise ValueError('the given repo {} has no version tags'.format(repo))
     tag, version = sorted(current_version_tags.items(), key=lambda _: _[1])[-1]
     _LOG.log(logging.NOTSET, 'result is %s and %s', tag, version)
     return commit, tag, version, commit_distance

version_query/query.py

@@ -37,15 +37,27 @@ def query_folder(path: pathlib.Path, search_parent_directories: bool = False) ->
 
 
 def query_caller(stack_level: int = 1) -> Version:
+    """Determine the version of code associated with the caller of this function."""
     here = _caller_folder(stack_level + 1)
     return query_folder(here, True)
 
 
 def query_version_str() -> str:
+    """Determine the version of code that calls this function and get it as string.
+
+    You can use this utility function like this:
+
+    '''
+    from version_query import query_version_str
+
+    VERSION = query_version_str()
+    '''
+    """
     return query_caller(2).to_str()
 
 
 def predict_folder(path: pathlib.Path, search_parent_directories: bool = True) -> Version:
+    """Predict version of code residing in a given folder."""
     priority_cutoff = 2
     paths = [path] + (list(path.parents)[:priority_cutoff] if search_parent_directories else [])
     for pth in paths:
@@ -71,4 +83,14 @@ def predict_caller(stack_level: int = 1) -> Version:
 
 
 def predict_version_str() -> str:
+    """Predict version of the code that calls this function and get it as string.
+
+    You can use this utility function like this:
+
+    '''
+    from version_query import predict_version_str
+
+    VERSION = predict_version_str()
+    '''
+    """
     return predict_caller(2).to_str()