Merge branch 'main' into fix/issue-1105-low-rank-spin-exchange

Author: rosspeili

CONTRIBUTING.md

@@ -249,14 +249,21 @@ make Mypy run in parallel for a substantial speed increase.
 
 Code should meet common style standards for Python and be free of error-prone constructs. We use
 [Pylint](https://www.pylint.org/) to check for code lint and [Black](https://github.com/psf/black)
-for formatting code.
+for formatting code, and provide scripts to run them.
 
 *   To check that code is formatted properly after editing Python files:
 
     ```shell
     check/format-incremental
     ```
 
+    If formatting issues are reported, you can fix them automatically by running the script with
+    the `--apply` option:
+
+    ```shell
+    check/format-incremental --apply
+    ```
+
 *   To run the linter:
 
     ```shell
@@ -289,8 +296,8 @@ We use [pytest](https://docs.pytest.org) to run our tests and
     `pytest -m "not slow" PATH`, where `PATH` is a directory or pytest file to test.
 
 *   After finishing a task, run `check/pytest` to test all of the OpenFermion code. If your system
-    has multiple processor cores, you can add the option `-n auto` to make it run in parallel for a
-    substantial speed increase. (Beware, though, that this is resource-intensive.)
+    has multiple processor cores, you can add the option `-n auto` to make pytest use multiple
+    parallel processes for a speed increase. (Beware, though, that this is resource-intensive.)
 
 We don't require 100% coverage, but coverage should be very high, and any uncovered code must be
 annotated with `# pragma: no cover`. To ignore coverage of a single line, place `# pragma: no cover`
@@ -301,7 +308,7 @@ cover` comment on its own line. Note, however, that these annotations should be
 
 After a task is finished, run each of the following to make sure everything passes all the tests:
 
-*   `check/format-incremental`
+*   `check/format-incremental` (and `check/format-incremental --apply` to auto-fix format problems)
 *   `check/pylint -j 0`
 *   `check/mypy`
 *   `check/pytest -n auto`

dev_tools/check_incremental_coverage_annotations.py

@@ -22,7 +22,7 @@
 from dev_tools.incremental_coverage import check_for_uncovered_lines
 
 
-def main():
+def main() -> None:
     if len(sys.argv) < 2:
         print(
             shell_tools.highlight(

dev_tools/docs/build_api_docs.py

@@ -15,6 +15,7 @@
 """Tool to generate external api_docs for OF (Shameless copy from TFQ)."""
 
 import os
+from typing import Any
 
 from absl import app
 from absl import flags
@@ -39,7 +40,7 @@
 FLAGS = flags.FLAGS
 
 
-def main(unused_argv):
+def main(unused_argv: Any) -> None:
 
     doc_generator = generate_lib.DocGenerator(
         root_title="OpenFermion",

dev_tools/env_tools.py

@@ -68,7 +68,7 @@ def prepare_temporary_test_environment(
     verbose: bool,
     env_name: str = '.test_virtualenv',
     python_path: str = sys.executable,
-    commit_ids_known_callback: Callable[[PreparedEnv], None] = None,
+    commit_ids_known_callback: Optional[Callable[[PreparedEnv], None]] = None,
 ) -> PreparedEnv:
     """Prepares a temporary test environment at the (existing empty) directory.
 

dev_tools/incremental_coverage.py

@@ -109,7 +109,7 @@ def diff_to_new_interesting_lines(unified_diff_lines: List[str]) -> Dict[int, st
     return interesting_lines
 
 
-def fix_line_from_coverage_file(line):
+def fix_line_from_coverage_file(line: str) -> str:
     line = line.rstrip()
     if line.startswith('!'):
         line = line[1:]

dev_tools/incremental_coverage_test.py

@@ -15,7 +15,7 @@
 from dev_tools import incremental_coverage
 
 
-def test_determine_ignored_lines():
+def test_determine_ignored_lines() -> None:
     f = incremental_coverage.determine_ignored_lines
 
     assert f("a = 0  # coverage: ignore") == {1}

dev_tools/prepared_env.py

@@ -65,7 +65,7 @@ def bin(self, program: str) -> str:
 
     def report_status_to_github(
         self, state: str, description: str, context: str, target_url: Optional[str] = None
-    ):
+    ) -> None:
         """Sets a commit status indicator on github.
 
         If not running from a pull request (i.e. repository is None), then this

dev_tools/prepared_env_security_test.py

@@ -1,12 +1,13 @@
 import unittest
+from typing import Any
 from unittest.mock import patch, MagicMock
 from dev_tools.prepared_env import PreparedEnv
 from dev_tools.github_repository import GithubRepository
 
 
 class TestPreparedEnvSecurity(unittest.TestCase):
     @patch('requests.post')
-    def test_report_status_to_github_token_in_header(self, mock_post):
+    def test_report_status_to_github_token_in_header(self, mock_post: Any) -> None:
         # Setup
         mock_response = MagicMock()
         mock_response.status_code = 201

dev_tools/requirements/run-pip-compiles.py

@@ -40,7 +40,7 @@
 import subprocess
 from argparse import ArgumentParser
 from dataclasses import dataclass, field
-from typing import *
+from typing import Any, Dict, Set
 
 
 @dataclass
@@ -83,12 +83,14 @@ class PlatformRecipe:
 }
 
 
-def run(*args):
+def run(*args: Any) -> subprocess.CompletedProcess:
     """Run a command using `subprocess`."""
     return subprocess.run(*args, check=True)
 
 
-def pip_compile(env_name: str, env_recipe: EnvRecipe, env_out_dir: str, constrain=True):
+def pip_compile(
+    env_name: str, env_recipe: EnvRecipe, env_out_dir: str, constrain: bool = True
+) -> None:
     """Run `pip-compile` to create the named environment."""
     dep_args = [f"deps/{dep_name}.txt" for dep_name in env_recipe.deps]
     dep_args += [f"--constraint=deps/{cons_name}.txt" for cons_name in env_recipe.addtl_constraints]
@@ -115,7 +117,7 @@ def get_dev_env_recipe(pr: PlatformRecipe) -> EnvRecipe:
     return EnvRecipe(all_deps, all_addtl_constraints)
 
 
-def make_platform_envs(pr: PlatformRecipe):
+def make_platform_envs(pr: PlatformRecipe) -> None:
     os.makedirs(pr.env_out_dir, exist_ok=True)
 
     # Pip compile the full dev environment
@@ -126,7 +128,7 @@ def make_platform_envs(pr: PlatformRecipe):
         pip_compile(env_name, env_recipe, pr.env_out_dir)
 
 
-def parse():
+def parse() -> None:
     """Parse command line arguments."""
     parser = ArgumentParser()
     parser.add_argument("--platform", default="default")
@@ -136,7 +138,7 @@ def parse():
     except KeyError:
         raise ValueError(f"Unknown platform {args.platform}")
 
-    return make_platform_envs(platform)
+    make_platform_envs(platform)
 
 
 if __name__ == "__main__":

dev_tools/shell_tools.py

@@ -124,7 +124,7 @@ def run_cmd(
     raise_on_fail: bool = True,
     log_run_to_stderr: bool = True,
     abbreviate_non_option_arguments: bool = False,
-    **kwargs,
+    **kwargs: Any,
 ) -> CommandOutput:
     """Invokes a subprocess and waits for it to finish.
 
@@ -204,7 +204,7 @@ def run_shell(
     err: Optional[Union[TeeCapture, IO[str]]] = sys.stderr,
     raise_on_fail: bool = True,
     log_run_to_stderr: bool = True,
-    **kwargs,
+    **kwargs: Any,
 ) -> CommandOutput:
     """Invokes a shell command and waits for it to finish.
 
@@ -267,7 +267,7 @@ def run_shell(
     return result
 
 
-def output_of(*cmd: Optional[str], **kwargs) -> str:
+def output_of(*cmd: Optional[str], **kwargs: Any) -> str:
     """Invokes a subprocess and returns its output as a string.
 
     Args:
@@ -276,9 +276,7 @@ def output_of(*cmd: Optional[str], **kwargs) -> str:
             a cwd (current working directory) argument.
 
     Returns:
-        A (captured output, captured error output, return code) triplet. The
-        captured outputs will be None if the out or err parameters were not set
-        to an instance of TeeCapture.
+        The output of the command.
 
     Raises:
          subprocess.CalledProcessError: The process returned a non-zero error