Typing

.github/workflows/test.yml

@@ -44,3 +44,7 @@ jobs:
       - name: Local integration tests
         run: pytest -m local
         if: ${{ matrix.os != 'windows-2019' }}
+
+      - name: Mypy typing checks
+        run: mypy pyinfra/ pyinfra_cli/
+        if: ${{ matrix.os == 'ubuntu-18.04' && matrix.python-version == '3.8' }}

MANIFEST.in

@@ -1 +1,2 @@
-include README.md LICENSE.md CHANGELOG.md
+include README.md LICENSE.md CHANGELOG.md pyinfra/py.typed
+global-include *.pyi

pyinfra/__init__.py

@@ -11,18 +11,19 @@
 # Global pyinfra logger
 logger = logging.getLogger('pyinfra')
 
-# Setup package level version
-from .version import __version__  # noqa
+from . import pseudo_modules  # noqa: E402
+from .version import __version__  # noqa: E402, F401
 
-# Trigger pseudo_* creation
-from . import pseudo_modules  # noqa
-
-# Trigger fact index creation
-from . import facts  # noqa
-
-# Trigger module imports
-from . import operations  # noqa # pragma: no cover
+# Setup pseudo modules
+state = pseudo_state = pseudo_modules.pseudo_state
+host = pseudo_host = pseudo_modules.pseudo_host
+inventory = pseudo_inventory = pseudo_modules.pseudo_inventory
 
 # Initialise base classes - this sets the pseudo modules to point at the underlying
 # class objects (Host, etc), which makes ipython/etc work as expected.
 pseudo_modules.init_base_classes()
+
+# TODO: remove this once we have explicit fact importing (break in v2)
+# Trigger fact/operations index creation
+from . import facts  # noqa
+from . import operations  # noqa # pragma: no cover

pyinfra/api/facts.pyi

@@ -0,0 +1,81 @@
+from typing import Any, Callable, Generic, Optional, Type, Union
+
+FACTS: Any
+FACT_LOCK: Any
+SUDO_REGEX: str
+SU_REGEXES: Any
+
+
+def is_fact(name: str):
+    ...
+
+
+def get_fact_class(name: str):
+    ...
+
+
+def get_fact_names():
+    ...
+
+
+class FactMeta(type):
+    def __init__(cls, name: str, bases: Any, attrs: dict) -> None:
+        ...
+
+
+class FactBase(Generic, metaclass=FactMeta):
+    abstract: bool = ...
+    shell_executable: Optional[Union[str, Callable]] = ...
+    requires_command: Optional[Union[str, Callable]] = ...
+
+    @staticmethod
+    def default() -> Any:
+        ...
+
+    @staticmethod
+    def process(output: list[str]) -> Any:
+        ...
+
+    def process_pipeline(self, args: Any, output: Any):
+        ...
+
+
+class ShortFactBase(metaclass=FactMeta):
+    fact: Type[FactBase] = ...
+
+
+def get_short_facts(state: Any, short_fact: Any, **kwargs: Any):
+    ...
+
+
+def get_facts(
+    state: Any,
+    name: Any,
+    args: Optional[Any] = ...,
+    ensure_hosts: Optional[Any] = ...,
+    apply_failed_hosts: bool = ...,
+):
+    ...
+
+
+def get_host_fact(state: Any, host: Any, name: Any):
+    ...
+
+
+def create_host_fact(
+    state: Any,
+    host: Any,
+    name: Any,
+    data: Any,
+    args: Optional[Any] = ...,
+) -> None:
+    ...
+
+
+def delete_host_fact(
+    state: Any,
+    host: Any,
+    name: Any,
+    args: Optional[Any] = ...,
+) -> None:
+    ...

pyinfra/api/operation.pyi

@@ -0,0 +1,32 @@
+from typing import Any, Callable, Optional
+
+OPERATIONS: Any
+
+
+def get_operation_names():
+    ...
+
+
+class OperationMeta:
+    commands: Any = ...
+    hash: Any = ...
+    changed: Any = ...
+
+    def __init__(self, hash: Optional[Any] = ..., commands: Optional[Any] = ...) -> None:
+        ...
+
+
+def add_op(state: Any, op_func: Any, *args: Any, **kwargs: Any):
+    ...
+
+
+def show_set_name_warning(call_location: Any) -> None:
+    ...
+
+
+def show_state_host_arguments_warning(call_location: Any) -> None:
+    ...
+
+
+def operation(func: Optional[Callable[..., Any]] = ..., pipeline_facts: Optional[Any] = ...):
+    ...

pyinfra/operations/files.py

@@ -14,7 +14,7 @@
 
 import six
 
-from jinja2 import TemplateRuntimeError, TemplateSyntaxError, UndefinedError
+from jinja2 import TemplateError, UndefinedError
 
 from pyinfra import logger
 from pyinfra.api import (
@@ -802,7 +802,7 @@ def template(
     # Render and make file-like it's output
     try:
         output = get_template(src).render(data)
-    except (TemplateRuntimeError, TemplateSyntaxError, UndefinedError) as e:
+    except (TemplateError, UndefinedError) as e:
         trace_frames = traceback.extract_tb(sys.exc_info()[2])
         trace_frames = [
             frame for frame in trace_frames

pyinfra/pseudo_modules.py

@@ -9,10 +9,6 @@
 executing in CLI mode).
 '''
 
-import sys
-
-import pyinfra
-
 
 class PseudoModule(object):
     _module = None
@@ -57,23 +53,9 @@ def isset(self):
         return self._module is not None
 
 
-# The current deploy state
-pseudo_state = \
-    sys.modules['pyinfra.pseudo_state'] = sys.modules['pyinfra.state'] = \
-    pyinfra.pseudo_state = pyinfra.state = \
-    PseudoModule()
-
-# The current deploy inventory
-pseudo_inventory = \
-    sys.modules['pyinfra.pseudo_inventory'] = sys.modules['pyinfra.inventory'] = \
-    pyinfra.pseudo_inventory = pyinfra.inventory = \
-    PseudoModule()
-
-# The current target host
-pseudo_host = \
-    sys.modules['pyinfra.pseudo_host'] = sys.modules['pyinfra.host'] = \
-    pyinfra.pseudo_host = pyinfra.host = \
-    PseudoModule()
+pseudo_state = PseudoModule()
+pseudo_inventory = PseudoModule()
+pseudo_host = PseudoModule()
 
 
 def init_base_classes():

setup.cfg

@@ -21,6 +21,10 @@ whitelist = words.txt
 dictionaries=en_US,python,technical,django
 
 
+[mypy]
+ignore_missing_imports = true
+
+
 [coverage:report]
 show_missing = true
 skip_covered = true

setup.py

@@ -41,6 +41,9 @@
     'mock==3.0.5',
     'codecov==2.1.8',
 
+    # Type checking
+    'mypy==0.790 ; python_version >= "3"',
+
     # Linting
     'flake8==3.8.3',
     'flake8-commas==2.0.0',