refactor!(mypy): additional type annotations and safety (#362)

See also: http://mypy-lang.org/

Author: tony

.github/workflows/tests.yml

@@ -41,6 +41,9 @@ jobs:
       - name: Lint with flake8
         run: poetry run flake8
 
+      - name: Lint with mypy
+        run: poetry run mypy .
+
       - name: Print python versions
         run: |
           python -V

CHANGES

@@ -70,6 +70,19 @@ $ pip install --user --upgrade --pre libvcs
 
 ### Internals
 
+- {issue}`362` [mypy] support added:
+
+  - Basic mypy tests now pass
+  - Type annotations added, including improved typings for:
+
+    - {meth}`libvcs._internal.subprocess.SubprocessCommand.run`
+    - {meth}`libvcs._internal.subprocess.SubprocessCommand.Popen`
+    - {meth}`libvcs._internal.subprocess.SubprocessCommand.check_output`
+    - {meth}`libvcs._internal.subprocess.run.run`
+
+  - `make mypy` and `make watch_mypy`
+  - Automatic checking on CI
+
 - {issue}`345` `libvcs.utils` -> `libvcs._internal` to make it more obvious the APIs are strictly
   closed.
 - `StrOrPath` -> `StrPath`
@@ -86,6 +99,9 @@ $ pip install --user --upgrade --pre libvcs
 ### Documentation
 
 - Document `libvcs.types`
+- {issue}`362`: Improve developer documentation to note [mypy] and have tabbed examples for flake8.
+
+[mypy]: http://mypy-lang.org/
 
 ### Packaging
 

docs/conf.py

@@ -15,7 +15,7 @@
 sys.path.insert(0, str(doc_path / "_ext"))
 
 # package data
-about = {}
+about: dict = {}
 with open(project_root / "libvcs" / "__about__.py") as fp:
     exec(fp.read(), about)
 
@@ -58,8 +58,8 @@
 html_extra_path = ["manifest.json"]
 html_favicon = "_static/favicon.ico"
 html_theme = "furo"
-html_theme_path = []
-html_theme_options = {
+html_theme_path: list = []
+html_theme_options: dict = {
     "light_logo": "img/libvcs.svg",
     "dark_logo": "img/libvcs.svg",
     "footer_icons": [

docs/contributing/workflow.md

@@ -6,18 +6,24 @@
 
 [poetry] is a required package to develop.
 
+```console
+$ git clone https://github.com/vcs-python/libvcs.git
 ```
-git clone https://github.com/vcs-python/libvcs.git
-cd libvcs
-poetry install -E "docs test coverage lint format"
+
+```console
+$ cd libvcs
+```
+
+```console
+$ poetry install -E "docs test coverage lint format"
 ```
 
 Makefile commands prefixed with `watch_` will watch files and rerun.
 
 ## Tests
 
-```
-poetry run py.test
+```console
+$ poetry run py.test
 ```
 
 Helpers: `make test` Rerun tests on file change: `make watch_test` (requires [entr(1)])
@@ -43,13 +49,105 @@ Rebuild docs on file change: `make watch_docs` (requires [entr(1)])
 Rebuild docs and run server via one terminal: `make dev_docs` (requires above, and a `make(1)` with
 `-J` support, e.g. GNU Make)
 
-## Formatting / Linting
+## Formatting
+
+The project uses [black] and [isort] (one after the other). Configurations are in `pyproject.toml`
+and `setup.cfg`:
+
+- `make black isort`: Run `black` first, then `isort` to handle import nuances
+
+## Linting
+
+[flake8] and [mypy] run via CI in our GitHub Actions. See the configuration in `pyproject.toml` and
+`setup.cfg`.
+
+### flake8
+
+[flake8] provides fast, reliable, barebones styling and linting.
+
+````{tab} Command
+
+poetry:
+
+```console
+$ poetry run flake8
+```
+
+If you setup manually:
+
+```console
+$ flake8
+```
+
+````
+
+````{tab} make
+
+```console
+$ make flake8
+```
+
+````
+
+````{tab} Watch
+
+```console
+$ make watch_flake8
+```
 
-The project uses [black] and [isort] (one after the other) and runs [flake8] via CI. See the
-configuration in `pyproject.toml` and `setup.cfg`:
+requires [`entr(1)`].
+
+````
+
+````{tab} Configuration
+
+See `[flake8]` in setup.cfg.
+
+```{literalinclude} ../../setup.cfg
+:language: ini
+:start-at: "[flake8]"
+:end-before: "[isort]"
+
+```
+
+````
+
+### mypy
+
+[mypy] is used for static type checking.
+
+````{tab} Command
+
+poetry:
+
+```console
+$ poetry run mypy .
+```
+
+If you setup manually:
+
+```console
+$ mypy .
+```
+
+````
+
+````{tab} make
+
+```console
+$ make mypy
+```
+
+````
+
+````{tab} Watch
+
+```console
+$ make watch_mypy
+```
 
-`make black isort`: Run `black` first, then `isort` to handle import nuances `make flake8`, to watch
-(requires `entr(1)`): `make watch_flake8`
+requires [`entr(1)`].
+````
 
 ## Releasing
 
@@ -67,6 +165,8 @@ Update `__version__` in `__about__.py` and `pyproject.toml`::
 
 [poetry]: https://python-poetry.org/
 [entr(1)]: http://eradman.com/entrproject/
+[`entr(1)`]: http://eradman.com/entrproject/
 [black]: https://github.com/psf/black
 [isort]: https://pypi.org/project/isort/
 [flake8]: https://flake8.pycqa.org/
+[mypy]: http://mypy-lang.org/

libvcs/_internal/run.py

@@ -178,7 +178,7 @@ def run(
     shell: bool = False,
     cwd: Optional[StrOrBytesPath] = None,
     env: Optional[_ENV] = None,
-    universal_newlines: Optional[bool] = None,
+    universal_newlines: bool = False,
     startupinfo: Optional[Any] = None,
     creationflags: int = 0,
     restore_signals: bool = True,
@@ -262,15 +262,15 @@ def progress_cb(output, timestamp):
         umask=umask,
     )
 
-    all_output = []
+    all_output: list[str] = []
     code = None
     line = None
     while code is None:
         code = proc.poll()
 
         # output = console_to_str(proc.stdout.readline())
         # all_output.append(output)
-        if callback and callable(callback):
+        if callback and callable(callback) and proc.stderr is not None:
             line = console_to_str(proc.stderr.read(128))
             if line:
                 callback(output=line, timestamp=datetime.datetime.now())