Merge pull request innogames#24 from hasegeli/master

kofrezo · web-flow · commit 53ea7897b876 · 2021-01-21T17:49:20.000+01:00
Improve code documentation
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,7 @@
 The MIT License (MIT)
 
-Copyright (c) 2020 InnoGames GmbH
+Copyright (c) 2021 InnoGames GmbH
+Portions Copyright (c) 2021 Emre Hasegeli
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/README.rst b/README.rst
@@ -89,16 +89,17 @@ configuration files has to be on the top level of the Git repository.
 ============== ========================================== ========
 Syntax Checker Configuration File
 ============== ========================================== ========
+coffeelint coffeelint.json, or package.json optional
 csslint .csslintrc optional
-htmlhint .htmlhintrc optional
-puppet-lint .puppet-lint.rc optional
-flake8 .flake8, setup.cfg, or tox.ini optional
-pycodestyle setup.cfg, or tox.ini optional
 eslint eslint.(js|yaml|yml|json), or package.json required
-jshint .jshintrc, or package.json optional
+flake8 .flake8, setup.cfg, or tox.ini optional
+htmlhint .htmlhintrc optional
 jscs .jscsrc, .jscs.json, or package.json required
-coffeelint coffeelint.json, or package.json optional
+jshint .jshintrc, or package.json optional
 phpcs phpcs.xml, or phpcs.xml.dist optional
+puppet-lint .puppet-lint.rc optional
+pycodestyle setup.cfg, or tox.ini optional
+rubocop .rubocop.yml optional
 ============== ========================================== ========
 
 
diff --git a/igcommit-receive b/igcommit-receive
@@ -1,7 +1,8 @@
 #!/usr/bin/env python
 """igcommit - The Git pre-receive hook to validate commits
 
-Copyright (c) 2020 InnoGames GmbH
+Copyright (c) 2021 InnoGames GmbH
+Portions Copyright (c) 2021 Emre Hasegeli
 """
 # NOTE: This binary is provided for convenience. It is nice to be able to run
 # the checks from the repository. This is not included on the releases. We
diff --git a/igcommit/__init__.py b/igcommit/__init__.py
@@ -1,6 +1,7 @@
 """igcommit - The main module
 
-Copyright (c) 2020 InnoGames GmbH
+Copyright (c) 2021 InnoGames GmbH
+Portions Copyright (c) 2021 Emre Hasegeli
 """
 
 VERSION = (3, 1)
diff --git a/igcommit/base_check.py b/igcommit/base_check.py
@@ -1,6 +1,7 @@
 """igcommit - The base check class
 
-Copyright (c) 2020 InnoGames GmbH
+Copyright (c) 2021 InnoGames GmbH
+Portions Copyright (c) 2021 Emre Hasegeli
 """
 
 from enum import IntEnum
diff --git a/igcommit/commit_checks.py b/igcommit/commit_checks.py
@@ -1,6 +1,7 @@
 """igcommit - Checks on Git commits
 
-Copyright (c) 2020 InnoGames GmbH
+Copyright (c) 2021 InnoGames GmbH
+Portions Copyright (c) 2021 Emre Hasegeli
 """
 
 from igcommit.base_check import BaseCheck, Severity
diff --git a/igcommit/commit_list_checks.py b/igcommit/commit_list_checks.py
@@ -1,6 +1,7 @@
 """igcommit - Checks on Git commit lists
 
-Copyright (c) 2020 InnoGames GmbH
+Copyright (c) 2021 InnoGames GmbH
+Portions Copyright (c) 2021 Emre Hasegeli
 """
 
 from time import time
diff --git a/igcommit/config.py b/igcommit/config.py
@@ -1,6 +1,7 @@
 """igcommit - Configuration of the checks
 
-Copyright (c) 2020 InnoGames GmbH
+Copyright (c) 2021 InnoGames GmbH
+Portions Copyright (c) 2021 Emre Hasegeli
 """
 
 from json import loads
diff --git a/igcommit/file_checks.py b/igcommit/file_checks.py
@@ -1,9 +1,9 @@
 """igcommit - Checks on files committed to Git
 
-Copyright (c) 2020 InnoGames GmbH
+Copyright (c) 2021 InnoGames GmbH
+Portions Copyright (c) 2021 Emre Hasegeli
 """
 
-from json.decoder import JSONDecodeError
 from os import remove
 from os.path import exists
 from subprocess import PIPE, Popen, STDOUT
diff --git a/igcommit/git.py b/igcommit/git.py
@@ -1,6 +1,7 @@
 """igcommit - Git routines
 
-Copyright (c) 2020 InnoGames GmbH
+Copyright (c) 2021 InnoGames GmbH
+Portions Copyright (c) 2021 Emre Hasegeli
 """
 
 from os.path import isabs, join as joinpath, normpath
diff --git a/igcommit/prereceive.py b/igcommit/prereceive.py
@@ -1,6 +1,7 @@
 """igcommit - Pre-receive hook routines
 
-Copyright (c) 2020 InnoGames GmbH
+Copyright (c) 2021 InnoGames GmbH
+Portions Copyright (c) 2021 Emre Hasegeli
 """
 
 from fileinput import input
@@ -37,6 +38,8 @@ def run():
 # Parallelization only applies to the CheckCommands. It has no overhead,
 # because we have to run those commands the same way externally, anyway.
 # We only have a limit to avoid consuming too many processes.
+ # (See iter_buffer() to understand how buffering causes parallel
+ # processing.)
 for check in iter_buffer(expand_checks(checks), 16):
 check.print_problems()
 assert check.state >= CheckState.DONE
@@ -46,6 +49,25 @@ def run():
 
 
 def expand_checks(checks):
+ """Clone, prepare, and yield the checks
+
+ This is the entry function to start processing the checks. The processing
+ is done in here for all inputs. They are the branches and the tags
+ pushed to Git and received by the prereceive hook.
+
+ The processing then continues to list of commits, the commits in every
+ list, and the files changed by those commits by the following functions.
+ Those functions clone the checks we start with in here for every object,
+ so we end up yielding a lot more checks than we start.
+
+ The checks are for different types of objects. Some of them checks
+ the list of commits, some particular commits, some just files. These
+ functions in here are agnostic about this. They would keep preparing
+ them on different levels with different types objects, and yield back
+ the ones that are cloned and become ready. The processing will stop
+ there. They will not be passed to the next function after they become
+ ready.
+ """
 checked_commit_ids = set()
 for line in input():
 for check in expand_checks_to_input(checks, line, checked_commit_ids):
diff --git a/igcommit/utils.py b/igcommit/utils.py
@@ -1,22 +1,56 @@
 """igcommit - Utility functions
 
-Copyright (c) 2020 InnoGames GmbH
+Copyright (c) 2021 InnoGames GmbH
+Portions Copyright (c) 2021 Emre Hasegeli
 """
 
 from os import X_OK, access, environ
 
 
 def get_exe_path(exe):
+ """Traverse the PATH to find where the executable is
+
+ This should behave similar to the shell built-in "which".
+ """
 for dir_path in environ['PATH'].split(':'):
 path = dir_path.strip('"') + '/' + exe
 if access(path, X_OK):
 return path
 
 
-def iter_buffer(iterable, amount):
+def iter_buffer(generator, amount):
+ """Iterate with buffering
+
+ This is a utility function that's useful for asynchronous processing.
+ It buffers the elements of the given generator to earn time for items
+ to do their processing.
+
+ The argument is assumed to be a generator (although it would work with
+ any iterable) that generates items which start their processing in
+ the background at the time they are generated. And the caller is assumed
+ to consume those items when their processing is complete.
+
+ This function is going to maintain a FIFO buffer up to the given size.
+ It'd start with an empty buffer (memo), buffer all of the generated items
+ until the buffer is full or the generator starts generating None, then
+ start adding items to the end yielding from the beginning of the buffer,
+ and finally yield the ones that are left in the buffer after the generator
+ is consumed.
+
+ The buffering is short-cut when the generator generates None as the next
+ item. This is a useful feature when the caller needs to wait for some
+ item in the buffer to complete. The generated None's are never yielded
+ to the caller.
+
+ Note that this procedure does not support out-of-order consumption of
+ the items. The caller would always have to wait for the first yielded
+ item to be done with its processing. While the caller is waiting,
+ another item in the buffer may become ready, but we wouldn't even know.
+ This is how this function remains very simple.
+ """
 assert amount > 1
 memo = []
- for elem in iterable:
+ for elem in generator:
 if elem is not None:
 memo.append(elem)
 if len(memo) < amount:

-Original file line number
+Diff line change
@@ @@ -1,9 +1,9 @@ @@
 """igcommit - Checks on files committed to Git
 -Copyright (c) 2020 InnoGames GmbH
 +Copyright (c) 2021 InnoGames GmbH
 +Portions Copyright (c) 2021 Emre Hasegeli
 """
 -fromjson.decoderimportJSONDecodeError
 fromosimportremove
 fromos.pathimportexists
 fromsubprocessimportPIPE, Popen, STDOUT