diff --git a/docsite/rst/developing_modules.rst b/docsite/rst/developing_modules.rst index aff5fab5567..596fa47417f 100644 --- a/docsite/rst/developing_modules.rst +++ b/docsite/rst/developing_modules.rst @@ -309,8 +309,7 @@ You should also never do this in a module:: print "some status message" -Because the output is supposed to be valid JSON. Except that's not quite true, -but we'll get to that later. +Because the output is supposed to be valid JSON. Modules must not output anything on standard error, because the system will merge standard out with standard error and prevent the JSON from parsing. Capturing standard @@ -343,7 +342,7 @@ and guidelines: * If packaging modules in an RPM, they only need to be installed on the control machine and should be dropped into /usr/share/ansible. This is entirely optional and up to you. -* Modules should return JSON or key=value results all on one line. JSON is best if you can do JSON. All return types must be hashes (dictionaries) although they can be nested. Lists or simple scalar values are not supported, though they can be trivially contained inside a dictionary. +* Modules should output valid JSON only. All return types must be hashes (dictionaries) although they can be nested. Lists or simple scalar values are not supported, though they can be trivially contained inside a dictionary. * In the event of failure, a key of 'failed' should be included, along with a string explanation in 'msg'. Modules that raise tracebacks (stacktraces) are generally considered 'poor' modules, though Ansible can deal with these returns and will automatically convert anything unparseable into a failed result. If you are using the AnsibleModule common Python code, the 'failed' element will be included for you automatically when you call 'fail_json'. @@ -351,21 +350,6 @@ and guidelines: * As results from many hosts will be aggregated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form. -.. _module_dev_shorthand: - -Shorthand Vs JSON -````````````````` - -To make it easier to write modules in bash and in cases where a JSON -module might not be available, it is acceptable for a module to return -key=value output all on one line, like this. The Ansible parser -will know what to do:: - - somekey=1 somevalue=2 rc=3 favcolor=red - -If you're writing a module in Python or Ruby or whatever, though, returning -JSON is probably the simplest way to go. - .. _module_documenting: Documenting Your Module