Document version/system/implementation checks that tools might want to support

[o11c]

A tool takes as input a python version, host system, python implementation, and body of python code, and returns a set of errors. Some tools may also support querying the type of an expression (e.g. for autocompletion of its attributes in an IDE).

How many and how finely it supports the platform checks, and whether it allows running checks for platforms other than the one it is currently running (simultaneously or in a separate run), is a QoI issue - this document nearly. However, tools should not make it impossible to check Windows-specific code from a Linux host.

At the very least, most tools will want to support python2 vs python3 detection.

Here's my list of branches that should be followed:

• assert and if statements with comparisons (==, !=, <, >, <=, >=; possibly chained like x < y < z), and and, not, and or expressions containing only comparisons, which contain only literals (of type str, int, or tuple of literals) and the following:
  • platform.python_version()
  • platform.python_version_tuple()
  • sys.version
  • sys.version_info
  • indexing and slices of the above
  • sys.hexversion
  • platform.python_implementation()
  • platform.system()
  • sys.platform maybe? (icky for e.g. linux2 vs linux)
  • Some way to specify that a value exported really is supposed to be constant.
    • "Anything that is not initialized to ..." would require changing many stubs that currently use x = ('', 0) as a short form of x = ... # type: Tuple[str, int].
    • Use this to implement a six stub via the above.
• else and elif branches following the above (not that elif need not have such an expression)
• Other:
  • if string_literal [not] in sys.modules maybe? Needs justification.
  • try ... except ImportError
  • try ... except AttributeError where the object is a module.
  • try ... except NameError for builtins e.g. unicode and long.

[matthiaskramm]

What would assert() do? Verify that a function isn't called in the wrong version of Python? How is that different to putting said function into an if sys.version_info ... block?

[o11c]

I originally wrote it without thinking, by way of comparison to if isinstance. This was before I thought out the module-level raise ImportError logic.

assert sys.version_info[0] >= 3 makes sense to be specially-interpreted at function scope, whereas raise ImportError should only be special at module scope. This might be within some non-obvious (to the type-checker) block.

[o11c]

Also startswith for sure ... possibly other split-type functions.

[o11c]

Since 3.3, there is sys.implementation.

[matthiaskramm]

Right now, version branches are barely used, so I'd start with something simple.
Just supporting sys.version_info > (major, minor, micro) and sys.platform == "win32" would already get us most of the way there, without placing an unnecessary burden on tools.

[JukkaL]

My vote goes to starting with the simplest possible rules that cover the (hopefully vast) majority of cases first, and once we have more experience we can decide to incrementally make it more general. There is always going to be an endless number of weird corner cases that are very rare and probably not worth supporting because of the added complexity.

[gvanrossum]

PEP 484 declares that the following should be supported:

  import sys

  if sys.version_info[0] >= 3:
      # Python 3 specific definitions
  else:
      # Python 2 specific definitions

  if sys.platform == 'win32':
      # Windows specific definitions
  else:
      # Posix specific definitions

Unfortunately mypy doesn't support these yet. (See python/mypy#698)

[gvanrossum]

Mypy now supports sys.version_info and sys.platform (and they are now heavily used in typeshed).