docs: Add documentation for `if False` mypy pattern in scripts.

This should help make it clear what's going on with these scripts.

docs/testing/mypy.md

@@ -96,6 +96,36 @@ an `Any` or `# type: ignore` so you're not blocked waiting for help,
 add a `# TODO: ` comment so it doesn't get forgotten in code review,
 and ask for help in chat.zulip.org.
 
+## mypy in production scripts
+
+While in most of the Zulip codebase, we can consistently use the
+`typing` module (Part of the standard library in Python 3.5, but
+present as an installable module with older Python), in our installer
+and other production scripts that might run outside a Zulip
+virtualenv, we cannot rely on the `typing` module being present on the
+system.
+
+To solve this problem, we use the following (semi-standard in the mypy
+community) hack in those scripts:
+
+```
+if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
+    from typing import List
+```
+
+and then use the Python 2 style type comment syntax for annotating
+those files.  This way, the Python interpreters for Python 2.7 and 3.4
+will ignore this line, and thus not crash.  But we can still get all
+the benefits of type annotations in that codebase, since the `mypy`
+type checker ignores the `if False` and thus still is able to
+type-check the file using those imports.
+
+The exception to this rule is that any scripts which use
+`setup_path_on_import` before they import from the `typing` module are
+safe.  These, we generally declare in the relevant exclude line in
+`tools/linter_lib/custom_check.py`
+
 ## mypy stubs for third-party modules.
 
 For the Python standard library and some popular third-party modules,

puppet/zulip/files/nagios_plugins/zulip_app_frontend/check_cron_file

@@ -5,8 +5,8 @@ file output by the cron job is correct.
 import sys
 import time
 
-# Avoid requiring the typing module to be installed
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Tuple
 
 def nagios_from_file(results_file: str, max_time_diff: int=60 * 2) -> 'Tuple[int, str]':

puppet/zulip/files/nagios_plugins/zulip_nagios_server/check_postgres_replication_lag

@@ -5,6 +5,7 @@ Nagios plugin to check the difference between the primary and
 secondary Postgres servers' xlog location.
 """
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from mypy_extensions import NoReturn
 
 import subprocess

puppet/zulip_ops/files/nagios_plugins/zulip_zephyr_mirror/check_personal_zephyr_mirrors

@@ -9,6 +9,7 @@ mirrors when they receive the messages sent every minute by
 /etc/cron.d/test_zephyr_personal_mirrors
 """
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Dict
 
 import os

puppet/zulip_ops/files/nagios_plugins/zulip_zephyr_mirror/check_user_zephyr_mirror_liveness

@@ -26,6 +26,7 @@ django.setup()
 from zerver.models import UserActivity
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Any, Dict, Set, Optional
 
 states = {

puppet/zulip_ops/files/nagios_plugins/zulip_zephyr_mirror/check_zephyr_mirror

@@ -10,6 +10,7 @@ run out of cron.
 See puppet/zulip_ops/files/cron.d/zephyr-mirror for the crontab details.
 """
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Dict
 
 import os

puppet/zulip_ops/files/zulip-ec2-configure-interfaces

@@ -54,6 +54,7 @@ import sys
 import boto.utils
 import netifaces
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Optional
 
 def address_of(device_id):

scripts/lib/clean_emoji_cache.py

@@ -4,6 +4,7 @@ import os
 import sys
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Set
 
 ZULIP_PATH = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

scripts/lib/clean_node_cache.py

@@ -5,6 +5,7 @@ import subprocess
 import sys
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Set
 
 ZULIP_PATH = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

scripts/lib/clean_venv_cache.py

@@ -4,8 +4,7 @@ import os
 import sys
 
 if False:
-    # Typing module isn't always available when this is run on older
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
-    # Python 3.4 (Trusty).
     from typing import Set
 
 ZULIP_PATH = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

scripts/lib/hash_reqs.py

@@ -1,12 +1,11 @@
 #!/usr/bin/env python3
-
-
 import os
 import sys
 import argparse
 import hashlib
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Iterable, List, MutableSet
 
 def expand_reqs_helper(fpath, visited):

scripts/lib/node_cache.py

@@ -4,6 +4,7 @@ import hashlib
 import json
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Optional, List, IO, Tuple, Any
 
 from scripts.lib.zulip_tools import subprocess_text_output, run

scripts/lib/setup_venv.py

@@ -13,7 +13,7 @@ if 'TRAVIS' in os.environ:
     VENV_CACHE_PATH = "/home/travis/zulip-venv-cache"
 
 if False:
-    # Don't add a runtime dependency on typing
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import List, Optional, Tuple, Set
 
 VENV_DEPENDENCIES = [

scripts/lib/zulip_tools.py

@@ -18,6 +18,7 @@ import uuid
 import configparser
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Sequence, Set, Any, Dict, List, Optional
 
 DEPLOYMENTS_DIR = "/home/zulip/deployments"

scripts/nagios/check-rabbitmq-consumers

@@ -9,6 +9,7 @@ import os
 import subprocess
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Any, Dict, Optional, Union
 
 states = {

scripts/nagios/cron_file_helper.py

@@ -1,7 +1,7 @@
 import time
 
-# Avoid requiring the typing module to be installed
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Tuple
 
 def nagios_from_file(results_file):

scripts/purge-old-deployments

@@ -5,6 +5,7 @@ import subprocess
 import sys
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Set
 
 ZULIP_PATH = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

scripts/setup/generate_secrets.py

@@ -4,6 +4,7 @@
 import sys
 import os
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Dict, List, Optional
 
 BASE_DIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

tools/diagnose

@@ -7,6 +7,7 @@ import sys
 import subprocess
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Callable, List
 
 TOOLS_DIR = os.path.dirname(__file__)

tools/lib/provision.py

@@ -25,6 +25,7 @@ from scripts.lib.node_cache import setup_node_modules, NODE_MODULES_CACHE_PATH
 
 from version import PROVISION_VERSION
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Any, List
 
 from tools.setup.generate_zulip_bots_static_files import generate_zulip_bots_static_files

tools/linter_lib/custom_check.py

@@ -877,6 +877,10 @@ def build_custom_checkers(by_lang):
          'description': 'Linkified markdown URLs should use cleaner <http://example.com> syntax.'},
         {'pattern': 'https://zulip.readthedocs.io/en/latest/[a-zA-Z0-9]',
          'exclude': ['docs/overview/contributing.md', 'docs/overview/readme.md', 'docs/README.md'],
+         'exclude_line': set([
+             ('docs/testing/mypy.md',
+              '# See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts')
+         ]),
          'include_only': set(['docs/']),
          'description': "Use relative links (../foo/bar.html) to other documents in docs/",
          },

tools/zulint/command.py

@@ -10,6 +10,7 @@ import subprocess
 import sys
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Any, Callable, Dict, List, Optional
 
 from zulint.printer import print_err, colors

tools/zulint/linters.py

@@ -3,6 +3,7 @@ from __future__ import absolute_import
 
 import subprocess
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import List
 
 from zulint.printer import print_err, colors

tools/zulint/lister.py

@@ -11,6 +11,7 @@ import argparse
 from six.moves import filter
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Union, List, Dict
 
 def get_ftype(fpath, use_shebang):

tools/zulint/printer.py

@@ -5,6 +5,7 @@ import sys
 import os
 from itertools import cycle
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from typing import Union, Text
 
 # Terminal Color codes for use in differentiatng linters

zthumbor/loaders/helpers.py

@@ -1,3 +1,4 @@
+# This file is used by both Python 2.7 (thumbor) and 3 (zulip).
 from __future__ import absolute_import
 
 import os
@@ -7,6 +8,7 @@ from six.moves.urllib.parse import urlparse
 from typing import Any, Text, Tuple, Optional
 
 if False:
+    # See https://zulip.readthedocs.io/en/latest/testing/mypy.html#mypy-in-production-scripts
     from thumbor.context import Context
 
 ZULIP_PATH = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath('__file__'))))