Closed
Description
This comes up pretty often, and it would be useful to have some documentation in the CONTRIBUTING.md file (or at least a link to this documentation).
Here's a starting point for what to document (there probably are other things that we should mention):
- If a function accepts both
str
and ascii-onlyunicode
arguments, usually the best type to use isUnion[str, unicode]
(orUnion[str, Text]
in a 2and3 stub). - Use
AnyStr
if you have two or more types in a signature that must agree on whether they arestr
orunicode
. (It would also be nice to give an example where this is important.) - You can also use
AnyStr
in invariant positions in generic type arguments. For example,List[AnyStr]
is generally better thanList[Union[str, unicode]]
(also explain why). However, often it's even better to use a covariant type such asIterable
orSequence
. In that case the union variant is preferable if the container may contain a mix ofstr
andunicode
. For example,Iterable[Union[str, unicode]]
is fine if the iterable may contain a mix ofstr
andunicode
values. - Try to avoid using
Union[str, unicode]
in a return type, since it means that every call site will have to deal with bothstr
andunicode
values. It may be fine to use this if the return type is sufficiently unpredictable. - Similarly, try to avoid using
Union[str, unicode]
as an attribute type -- again code using this attribute would have to deal with bothstr
andunicode
values.
Metadata
Metadata
Assignees
Labels
No labels