PEP-484 Type Annotations with own types

Question

PEP-484 provides semantics for type annotations. These are geared very much towards a) documentation and b) help for IDEs. They are less geared towards code optimization.

Answer 1

Since Python 3.5, we not only have the PEP 483, PEP 484, but also typing module that implements it.

For complete understanding, you might want to read through those 3 documents. But for your specific case, the short answer is that in PEP484 realm you can work with own types in 4 ways:

1. just annotate using own types,
2. create type aliases,
3. use NewType, or
4. use own generic types

---

If what you seek is above all else:

additional information visible to my own type checker, but invisible to any PEP-484 conforming type checker

then the 2nd approach gives you just that. If you do:

Int32 = int
Int64 = int

x = 0 # type: Int32
y = 0 # type: Int64

Then Int32 and Int64 would be the same in PEP484 realm, but you could add some additional checks by looking into the AST (Abstract Syntax Tree) of your code using community-maintained typed-ast module. That module parses type comments in addition to code, so you can read the exact annotation used, and thus get some additional type information for x and y.

---

And, if being invisible is not the number one priority, then:

• instead of class Int32(int): pass I would rather do typing.NewType('Int32', int), and

• instead of combine(Int32, Metre) I would use typing.Union[Int32, Metre].

i.e.

Int32 = typing.NewType('Int32', int)

class Metre:
    pass

x = [Int32(1)]  # type: List[Int32]
y = Int32(1) # type: typing.Union[Int32, Metre]

print(x[0] + 1) # ok, since Int32 is still int
y = Metre() # ok, since y can be Int32 or Metre

On the above code, you can run community-maintained static type-checker mypy.

---

Both typed-ast and mypy are now (year 2016) under very active development. Not everything works as expected, but as far as I can see they are good enough for many use cases already, and also there seem to be no alternatives.