{"id":344,"date":"2017-08-19T18:22:37","date_gmt":"2017-08-19T23:22:37","guid":{"rendered":"http:\/\/bluegalaxy.info\/codewalk\/?p=344"},"modified":"2017-08-19T21:11:35","modified_gmt":"2017-08-20T02:11:35","slug":"python-how-to-set-and-read-docstrings","status":"publish","type":"post","link":"https:\/\/bluegalaxy.info\/codewalk\/2017\/08\/19\/python-how-to-set-and-read-docstrings\/","title":{"rendered":"Python: How to set and read Docstrings"},"content":{"rendered":"

Docstrings are a triple quoted string that you declare at the beginning of object definitions such as functions, classes, and class methods. They are used to describe the purpose of the function, as a brief summary, but not describe how the function works<\/em>. To describe how a function works, you would use regular comments.<\/p>\n

A good Python coding habit is to include a docstring for every function, method or class object you write. Docstring conventions are outlined in PEP 257<\/a>.<\/p>\n

There are two ways that users can view your function’s docstrings, which illustrate why they are so useful.<\/p>\n

    \n
  1. The user can type help(function_name)<\/code> in the console or\u00a0print(help(function_name))<\/code>in an IDE and they will see the docstring listed under the function name as a handy summary of what the function does. For example:\n
    >>> help(docstring_test)\r\nHelp on function docstring_test in module __main__:\r\n\r\ndocstring_test()\r\n    This is the docstring in triple quotes, right below the function definition line.\r\n<\/pre>\n<\/li>\n
  2. The user can type function_name.__doc__<\/code>For example:\n
    >>> docstring_test.__doc__\r\n'This is the docstring in triple quotes, right below the function definition line.'<\/pre>\n<\/li>\n<\/ol>\n
    Here is a full code example:<\/p>\n
    def docstring_test():\r\n    \"\"\"This is the docstring in triple quotes, right below the function definition line.\"\"\"\r\n    print(\"This is how you access a docstring: \\nfunction_name.__doc__\")\r\n    print(docstring_test.__doc__)\r\n\r\ndocstring_test()<\/pre>\n
    Which yields:<\/p>\n
    This is how you access a docstring: \r\nfunction_name.__doc__\r\nThis is the docstring in triple quotes, right below the function definition line.<\/pre>\n
    For more information, see:
    \n    https:\/\/en.wikipedia.org\/wiki\/Docstring<\/a>
    \n    https:\/\/docs.python.org\/2\/tutorial\/controlflow.html#tut-docstrings<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
    Docstrings are a triple quoted string that you declare at the beginning of object definitions such as functions, classes, and class methods. They are used to describe the purpose of the function, as a brief summary, but not describe how the function works. To describe how a function works, you would use regular comments. A … Continue reading Python: How to set and read Docstrings<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[22],"tags":[27,24,4],"class_list":["post-344","post","type-post","status-publish","format-standard","hentry","category-python-language","tag-built-in-help-functions","tag-docstring","tag-python"],"_links":{"self":[{"href":"https:\/\/bluegalaxy.info\/codewalk\/wp-json\/wp\/v2\/posts\/344","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/bluegalaxy.info\/codewalk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/bluegalaxy.info\/codewalk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/bluegalaxy.info\/codewalk\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/bluegalaxy.info\/codewalk\/wp-json\/wp\/v2\/comments?post=344"}],"version-history":[{"count":14,"href":"https:\/\/bluegalaxy.info\/codewalk\/wp-json\/wp\/v2\/posts\/344\/revisions"}],"predecessor-version":[{"id":360,"href":"https:\/\/bluegalaxy.info\/codewalk\/wp-json\/wp\/v2\/posts\/344\/revisions\/360"}],"wp:attachment":[{"href":"https:\/\/bluegalaxy.info\/codewalk\/wp-json\/wp\/v2\/media?parent=344"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/bluegalaxy.info\/codewalk\/wp-json\/wp\/v2\/categories?post=344"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/bluegalaxy.info\/codewalk\/wp-json\/wp\/v2\/tags?post=344"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}