enforcing python function parameters types from docstring

Question

Both epydoc and Sphinx document generators permit the coder to annotate what the types should be of any/all function parameter.

My question is: Is there a way (or module) that enforces these types (at run-time) when documented in the docstring. This wouldn't be strong-typing (compile-time checking), but (more likely) might be called firm-typing (run-time checking). Maybe raising a "ValueError", or even better still... raising a "SemanticError"

Ideally there would already be something (like a module) similar to the " import antigravity " module as per xkcd , and this "firm_type_check" module would already exist somewhere handy for download.

FYI: The docstring for epydoc and sphinz are as follows:

epydoc: Functions and Methods parameters:

• @param p: ... # A description of the parameter p for a function or method.
• @type p: ... # The expected type for the parameter p.
• @return: ... # The return value for a function or method.
• @rtype: ... # The type of the return value for a function or method.
• @keyword p: ... # A description of the keyword parameter p.
• @raise e: ... # A description of the circumstances under which a function or method raises exception e.

Sphinx: Inside Python object description directives, reST field lists with these fields are recognized and formatted nicely:

• param, parameter, arg, argument, key, keyword: Description of a parameter.
• type: Type of a parameter.
• raises, raise, except, exception: That (and when) a specific exception is raised.
• var, ivar, cvar: Description of a variable.
• returns, return: Description of the return value.
• rtype: Return type.

The closest I could find was a mention by Guido in mail.python.org and created by Jukka Lehtosalo at Mypy Examples . CMIIW : mypy cannot be imported as a py3 module.

Similar stackoverflow questions that do not use the docstring per se:

• Pythonic Way To Check for A Parameter Type
• What's the canonical way to check for type in python?

Answer 1

To my knowledge, nothing of the sort exists, for a few important reasons:

• First, docstrings are documentation, just like comments. And just like comments, people will expect them to have no effect on the way your program works. Making your program's behavior depend on its documentation is a major antipattern, and a horrible idea all around.

• Second, docstrings aren't guaranteed to be preserved. If you run python with -OO , for example, all docstrings are removed. What then?

• Finally, Python 3 introduced optional function annotations, which would serve that purpose much better: http://legacy.python.org/dev/peps/pep-3107/ . Python currently does nothing with them (they're documentation), but if I were to write such a module, I'd use those, not docstrings.

My honest opinion is this: if you're gonna go through the (considerable) trouble of writing a (necessarily half-baked) static type system for Python, all the time it will take you would be put to better use by learning another programming language that supports static typing in a less insane way:

• Clojure ( http://clojure.org/ ) is incredibly dynamic and powerful (due to its nature as a Lisp) and supports optional static typing through core.typed ( https://github.com/clojure/core.typed ). It is geared towards concurrency and networking (it has STM and persistent data structures <3 ), has a great community, and is one of the most elegantly-designed languages I've seen. That said, it runs on the JVM, which is both a good and a bad thing.

• Golang ( http://golang.org/ ) feels sort-of Pythonic (or at least, it's attracting a lot of refugees from Python), is statically typed and compiles to native code.

• Rust ( http://www.rust-lang.org/ ) is lower-level than that, but it has one of the best type systems I've seen (type inference, pattern matching, traits, generics, zero-sized types...) and enforces memory and resource safety at compile time . It is being developed by Mozilla as a language to write their next browser (Servo) in, so performance and safety are its main goals. You can think of it as a modern take on C++. It compiles to native code, but hasn't hit 1.0 yet and as such, the language itself is still subject to change. Which is why I wouldn't recommend writing production code in it yet.