Decide how to deal with str/unicode

[JukkaL]

We should agree on how we expect the string types to be used in Python 2 code.

There are at least four ways we can approach this:

1. Make str usually valid when unicode is expected. This is how mypy currently works, and this is similar to how PEP 484 defines bytearray / bytes compatibility. This will correspond to runtime semantics, but it's not safe as non-ascii characters in str objects will result in programs sometimes blowing up. A 7-bit str instance is almost always valid at runtime when unicode is expected.
2. Get rid of the str -> unicode promotion and use Union[str, unicode] everywhere (or create an alias for it). This is almost like approach 1, except that we have a different name for unicode and more complex error messages and a complex programming model due to the proliferation of union types. There is potential for some additional type safety by using just unicode in user code.
3. Enforce explicit str / unicode distinction in Python 2 code, similar to Python 3 (str would behave more or less like Python 3 bytes), and discourage union types. This will make it harder to annotate existing Python 2 programs which often use the two types almost interchangeably, but it will make programs safer.
4. Have three different string types: bytes (distinct from from str) means 8-bit str instances -- these aren't compatible with unicode. str means ascii str instances. These are compatible with bytes and unicode, but not the other way around. unicode means unicode instances and isn't special. A string literal will have implicit type str or bytes depending on whether it only has ascii characters. This approach should be pretty safe and potentially also makes it fairly easy to adapt existing code, but harder than with approach 1.

These also affect how stubs should be written and thus it would be best if every tool using typeshed could use the same approach:

• For approach 1, stubs should usually use str, unicode or AnyStr. This is how many stubs are written already.
• For approach 2, stubs should use str, Uniont[str, unicode] or AnyStr for attributes and function arguments, and return types could additionally use plain unicode. Return types would in general be hard to specify precisely, as it may be difficult to predict whether a function called with str or combination of str and unicode returns str, unicode or Union[str, unicode]. In approach 1 we can safely fall back to unicode if unsure. AnyStr would be less useful as we could have mixed function arguments like (str, unicode) easily (see the typeshed issues mentioned below for more about this).
• For approach 3, stubs would usually use either str, unicode or AnyStr, but unicode wouldn't accept plain str objects.
• For approach 4, stubs could use three different types (bytes, str, unicode) in addition to AnyStr, and these would all behave differently. Unlike the first three approaches, AnyStr would range over str, unicode and bytes in Python 2 mode.

Note that mypy currently assumes approach 1 and I don't know how well the other approaches would work in practice.

[This was adapted from a comment on #1135; see the original issue for more discussion. Also, https://github.com/python/typeshed/issues/50 is relevant.]

[gvanrossum]

Maybe a fifth approach: write 'basestring' instead of Union[str, unicode](in places where that's preferred over AnyStr). That's how Python 2 code is
supposed to test for either, e.g. isinstance(x, basestring).

[JukkaL]

basestring would likely be quite similar to approach 1. We'd just a have different name for the type. Also, unicode would be a separate type -- that would have its pros and cons. Note that basestring doesn't actually define any methods so we'd be lying a bit by using it as a type, as it's not a real ABC, but I doubt it matters.

Let me sketch how this would work:

• basestring is a supertype of str and unicode. All operations on basestring return basestring objects, and basestring method arguments have basestring types. AnyStr would range over str, unicode and basestring. Stubs would generally use str, basestring or AnyStr but user code could also decide to use unicode.

The main new challenge compared to the first approach is that it may be difficult to make it practical to use unicode types everywhere in user code, as library functions returning basestring could screw things up. So it's going to be important that library functions in stubs usually don't return basestring but instead return AnyStr, for example.

[JukkaL]

An executive summary of the basestring approach I sketched above compared to approach 1:

Good: user code can opt for strict unicode checking, less hacky string subtyping

Bad: an extra string type makes things a little more complicated, stubs are harder to write, typeshed needs a major update, code using basestring needs extra conversions to use code that uses strict unicode

[gvanrossum]

I think AnyStr is probably the best approach for most cases, especially when the corresponding PY3 method uses it. But Matthias expressed a desire to use Union[str, unicode] in some places where a type variable is inappropriate. One example for this that I discovered is samefile(a, b) -> bool; this just calls os.stat(a) and os.stat(b), and there's no need for a and b to have the same type, even in PY3 (despite what typeshed/stdlib/3/os/path.pyi currently says). So I'm merely proposing basestring as an acceptable shortcut for Union[str, unicode] on PY2. (PY3 doesn't have it at all.) Off-topic: eventually I think it would be cool to have a way to run mypy and pytypes in "straddling" mode, where it checks compatibility with PY2 and PY3 simultaneously. Although I suppose you could emulate this by running it twice and merging the output.

[JukkaL]

Ah okay. I'm not excited about having union type as the default way of doing anything common, as they are unintuitive to use, even if there is a type alias behind them. If we are going to have a basetring type I'd suggest making it a class (essentially an ABC). This is clearly a philosophical difference between me and pytype, as pytype tends to infer a lot of union types and I've tried to avoid them as much as possible. I believe that pytype could still replace str or unicode in their inference results with basestring even if basestring was a class.

[gnprice]

As a bit of data on approach 1, several of the most frequently-hit exceptions in the Dropbox server codebase are UnicodeDecodeErrors and UnicodeEncodeErrors. It's not easy to tell for all of them, but many of them seem to be because a str is used where a unicode is expected or vice versa. So making the distinction sharply would actually be helpful for catching bugs.

[JukkaL]

Approaches 3 and 4 would give the most effective detection of Unicode related errors. Approaches 2 and 5 would give some detection but built-in methods would probably have to be permissive and there would still be room for runtime errors.

However, to adopt these strict approaches existing code may need a lot of work to pass type checking.

[gvanrossum]

So while in theory the return type of .encode() and .decode() depend on
the encoding name, in practice the types seem to be

basestring.encode(enc: str) -> bytes
basestring.decode(enc: str) -> unicode

[matthiaskramm]

I'm with Greg on this one. We want to explicitly distinguish between str and unicode, to shake out bugs.
One of the main reasons we're working on type checking is to help us port code to Python 3. The most difficult part of porting to Python 3 is dealing with str and unicode. If a type checker can help sort those out ahead of time, that's a win.

Also, basestring as a shortcut for Union[str, unicode] sounds useful.

[JukkaL]

I suggest that we take a few steps back and think about what we are trying to achieve via type checking.

Things that mypy can type check right now (using Python 3 syntax but Python 2 semantics):

a) Passing unicode when a function expects str

def f(x: str): ...
f(u'foo')   # Error

b) Adding unicode to a str collection (special case of a, really)

x = []  # type: List[str]
...
x[i] = u'foo'  # error

These would be easy to support with small stub changes:

c) Decode unicode

u'\u1234'.decode(...)

d) Encode str

'\xff'.encode('utf8')

Here are some additional things that we could catch if mypy did things differently:

1. Concatenating str and unicode (and related)

'\xff' + u'foo'
u'%s' % '\xff'
u'{}'.format('\xff')

2. Passing str to a user function when unicode is expected:

def f(x: unicode) -> None: ...
f('\xff')

3. Calling functions with a mix of str and unicode that can fail

os.path.join(u'foo', '\xff')

4. Adding strto a unicode collection

x = []  # type: List[unicode]
...
x[i] = '\xff'

[JukkaL]

[I submitted the previous comment accidentally when I was still writing it. I edited it afterwards but you may get an email with the old contents.]

As followup to the previous comment, we should decide whether we want to catch issues like 1, 2, 3 and 4. Just removing str -> unicode promotion (and using Union[str, unicode] or basestring instead of unicode in stubs) would help with 2), 3) and 4), but it wouldn't catch 1).

Also, as I mentioned earlier, we should look into how the changes affect type checking existing code, as there are some subtle interactions. The basestring change discussed earlier may affect type checking of functions that use AnyStr, in particular. Consider this function:

def f(a: AnyStr, b: AnyStr) -> AnyStr:
    return os.path.join('base', a, b)

Currently the function type checks fine, because 'base' is compatible with unicode. If we'd remove this compatibility, we'd have to modify it, such as like this:

def f(a: AnyStr, b: AnyStr) -> AnyStr:
    if isinstance(a, str):
        base = 'base'
    else:
        base = u'base'
    return os.path.join(base, a, b)

The modified version is much longer and also less efficient. I'm not sure if people would be happy to modify their code like that -- they might prefer to use Any types even if they could figure out how to change their code.

Also, consider a naive version of the annotated f:

def f(a: basestring, b: basestring) -> basestring:
    return os.path.join('base', a, b)

This looks fine on the surface, but the call to os.path.join would be rejected by a type checker because it mixes str and unicode.

However, consider a slightly different f body:

def f(a: basestring, b: basestring) -> basestring:
    return 'base' + '/' + a + '/' + b

This might actually not generate any type check errors (depending on how we deal with 1) above), even though it can fail similarly at runtime to the original f.

[JukkaL]

Another random idea: We could have an internal type called ascii_str that would be the type of a string literal that only has 7-bit characters. It would be a subtype of both str and unicode, but str would not be a subtype of unicode. Now the AnyStr example from above would work:

def f(a: AnyStr, b: AnyStr) -> AnyStr:
    return os.path.join('base', a, b)   
         # no need for isinstance(...) since 'base' has type 'ascii_str'

The ascii_str type wouldn't be supported in annotations and would only work locally within functions or expressions. This would be a variant of the original approach 4 -- now str would conform to bytes in approach 4 and ascii_str would correspond to str in approach 4. I'm not sure whether this would actually work in general, though (same applies to approach 4).

[gvanrossum]

I like having a variety of string types to express the various cases that occur in real PY2 code, while still catching as many bytes/unicode errors as possible.

The error cases are mostly code that mixes str and unicode instances assuming that the str instances are 7-bit while they occasionally contain 8-bit data. They will raise some UnicodeError only when given 8-bit data.

The false positives for such error checks would be code that looks the same as above but in reality only gets fed 7-bit data. My intuition is that the most common case for that is when the data is always coming from 7-bit string literals. So having a separate type inferred for 7-bit literals would be very useful.

I also like distinguishing between str and bytes even though they are the same class -- clarifying intention is the reason the bytes alias was introduced. (Note there's also a b'...' literal.)

Maybe we can draw up a class hierarchy including all the types we care about? I think the set of types would be:

• basestring
• bytes
• str
• unicode
• ascii_str

I think it's non-controversial that basestring is the base of them all, with bytes and unicode as distinct subtypes, but beyond that it's tricky. Maybe str could be another distinct subtype of basestring, with ascii_str being a subtype of all? I.e.

class basestring: ...
class bytes(basestring): ...  # type of b'...'
class str(basestring): ...  # type of '...' with some 8-bit chars
class unicode(basestring): ...  # type of u'...'
class ascii_str(bytes, str, unicode): ...  # type of '...' with only 7-bit chars

We would strive for most code to be annotated using mostly bytes and unicode, or str when it's "old school text processing". I'm fine with not having a way for user code to spell ascii_str, as long as it's inferred appropriately for literals.

I guess AnyStr should have all four as constraints! It would be useful for many os and os.path functions, and many things that call them.

Code would be prevented to mix bytes, str and unicode -- mixing bytes or str with unicode is the source of UnicodeErrors, while mixing bytes with str point to conceptual impurity that needs to be resolved before the code can be ported to PY3.

In order to make it easier to write straddling code, we can define typing.unicode as an alias for builtins.unicode in PY2, and for builtins.str in PY3. (I prefer this over borrowing the string types from six -- not everyone uses six in their straddling code.)

I expect that this scheme will cause a certain amount of pain when starting to annotate "wild west" (I mean "real world" :-) PY2 code, but the pain should be exactly in the places that would cause problems when porting to PY3 (or straddling).

I wonder if we could experiment with a new approach using a different command line flag? E.g. --py2-strict.