4

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:

Community
  • 1
  • 1
NevilleDNZ
  • 1,269
  • 12
  • 31
  • 1
    It doesn't read from docstrings, but https://pypi.python.org/pypi/typedecorator is a nice simple way of enforcing types with decorators. It also supports using Python 3 annotations (as suggested by http://stackoverflow.com/a/27402144/363836 below) – jwmullally Oct 12 '15 at 09:52
  • 1
    For python > 3.5: https://www.python.org/dev/peps/pep-0484/ – ederag Oct 08 '16 at 12:25

1 Answers1

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.

Max Noel
  • 8,810
  • 1
  • 27
  • 35
  • TBH: I'm just looking for a way to augment unit-testing... so the need for the optimisation option "-OO" is moot. Ideally I can just "turn it off" in production code. – NevilleDNZ Dec 10 '14 at 13:37
  • And **also** check that the docstring documentation is both accurate and up-to-date. – NevilleDNZ Dec 10 '14 at 14:11
  • Another important consideration is duck typing, which a *lot* of the Python ecosystem relies on: for example, most functions that take a `file` parameter will work fine with `StringIO` or `urllib.urlopen` objects instead, and brutal typechecking will cut you off from most of that power. Abstract base classes can alleviate that need somewhat, but they're far from perfect. – Max Noel Dec 10 '14 at 15:04
  • I cannot imagine that *every* parameter of *every* python function can be audited, but you raise an interesting point. Type-checking would naturally be hierarchical for sub-classes, for Duck-Typing I would imagine this is 99% attribute checking. So it's (kind of) the classic question of *name equivalence*, as opposed to *structural equivalence*, in this case *super-class* equivalence, as opposed to *attribute equivalence*. However (recall) I am simply trying (in this case) to augment my unit-testing and ensure that "most" docstrings are factual. – NevilleDNZ Dec 12 '14 at 00:19