Applying parameters of python function parameters from docstring
Both epydoc and Sphinx document generators allow the encoder to annotate what types any / all parameter of a function should have.
My question is, is there a way (or module) that enforces these types (at runtime) when documented in the docstring. It won't be strong-typing (compile-time checking), but (more likely) can be called a proprietary type (run-time checking). Possibly raising "ValueError" or even better ... raising "SemanticError"
Ideally, there will already be something (eg a module) similar to the " import antigravity
" xkcd module, and this "firm_type_check" module would already be somewhere convenient to load.
FYI: The docsrin for epidoc and sphinx is as follows:
epydoc: Parameters of functions and methods:
- @param p: ... # Description of the p parameter for a function or method.
- @type p: ... # Expected type for parameter p.
- @return: ... # Return value for a function or method.
- @rtype: ... # Return type for a function or method.
- @keyword p: ... # Description of the keyword p parameter.
- @raise e: ... # Describe the circumstances under which a function or method would throw an exception.
Sphinx: In object declaration directives inside Python, REST field lists with these fields are recognized and formatted nicely:
- param, parameter, arg, argument, key, keyword: Description of the parameter.
- type: The type of the parameter.
- raises raise, exception, exception: this is (and when) a specific exception is thrown.
- var, ivar, cvar: Variable description.
- returns, returns: Description of the return value.
- rtype: return type.
The closest I could find was Guido's mention at mail.python.org and created by Jukka Lehtosalo in Mypy Examples . CMIIW : mypy cannot be imported as py3 module.
Similar stackoverflow issues that don't use docstring as such:
source to share
As far as I know, nothing like this exists for several important reasons:
-
First, docstrings are documentation, as are comments. And just like comments, people will expect them not to affect how your program works. Your program behavior depends on its documentation - this is a major anti-pattern and a terrible idea.
-
Secondly, docs are not guaranteed. If you run
python
with-OO
, for example, all docstrings are removed. What then? -
Finally, Python 3 has introduced optional function annotations that will serve this purpose much better: http://legacy.python.org/dev/peps/pep-3107/ . Python currently doesn't do anything with them (that's the documentation), but if I were to write a module like this, I'd use those rather than docstrings.
My honest opinion is that if you run into the (significant) problem of writing a static type system (necessarily half baked) for Python, all the time it takes you would be better off learning another programming language that supports static typing in a less crazy way:
-
Clojure ( http://clojure.org/ ) is incredibly dynamic and powerful (due to its Lisp nature) and supports optional static text input via
core.typed
( https://github.com/clojure/core.typed ). It is focused on concurrency and networking (has STM and persistent data structures <3), has a great community, and is one of the most elegant languages I have seen. However, it runs on the JVM, which is good and bad. -
Golang ( http://golang.org/ ) feels like something like Pythonic (or at least attracts a lot of refugees from Python), is statically typed and compiled to native code.
-
Rust ( http://www.rust-lang.org/ ) is a lower level than that, but it has one of the best type systems I have (inference type, pattern matching, traits, generics, zero size types. ..) and ensures compile-time safety of memory and resources. It is being developed by Mozilla as the language for writing its next browser (Servo), so performance and security are its main goals. You can think of this as the modern C ++ perception. It compiles to native code, but hasn't hit 1.0 yet, and the language itself is still subject to change. This is why I would not recommend writing production code in it.
source to share