#docstring

之前提到了 if else 的應用， 也介紹了 Python 迴圈基礎， 隨著程式碼越來越大， 就需要透過函式來幫助處理重複的程式碼， 而這就是今天要介紹的主題 Python基礎：函式入門 透過 IDE 軟體 Pycharm ， 在新建 Python專案時， 選擇 create a main.py welcome script ， 就能快速建立一個可執行的 main 程式。 將其稍微修改下， def print_hi(name): """這是一個基本的範例函式""" print(f'Hi, {name}') if __name__ == '__main__': help(print_hi) print_hi('Kevin') 執行結果： print_hi(name) 這是一個基本的範例函式 Hi, Kevin Process finished with…

How-to: What is the standard Python docstring format? #solution #dev #answer

What is the standard Python docstring format?

I have seen a few different styles of writing docstrings in Python, is there an official or “agreed-upon” style?

Answer [by Amber]: What is the standard Python docstring format?

Python’s official styles are listed in PEP-8.

Answer [by bstpierre]: What is the standard Python docstring format?

PEP-8is the official python coding standard. It contains…

How to: Good examples of Python docstrings for Sphinx

Good examples of Python docstrings for Sphinx

Is anyone aware of any good examples of Python docstrings written with Sphinx autodoc in mind? It would be helpful to see how the docstrings are formatted (space, indentation, etc.) so that autodoc gives beautiful documentation.

Answer: Good examples of Python docstrings for Sphinx

For any sphinx documentation that you find on the web, you can click…

How to: What is the standard Python docstring format?

What is the standard Python docstring format?

I have seen a few different styles of writing docstrings in Python, is there an official or “agreed-upon” style?

Answer: What is the standard Python docstring format?

Python’s official styles are listed in PEP-8.

Answer: What is the standard Python docstring format?

PEP-8is the official python coding standard. It contains a section on docstrings,…

Python のテスティングフレームワーク nose を使ったテストには docstring を書いておくと結構便利。

#!/usr/bin/env python # -*- coding: utf-8 -*- import unittest import nose from nose.tools import assert_equal class Test(unittest.TestCase): def test_with_docstring(self): ''' すべてがFになる ''' assert_equal(-~0xfffffffe, 0xffffffff) if __name__ == "__main__": nose.main(argv=['nosetests', '-v'], defaultTest=__file__)

もちろん docstring がテストの説明になるってのもそうなんだけど、テストの実行結果まで docstring の内容になるため。

すべてがFになる ... ok ---------------------------------------------------------------------- Ran 1 test in 0.001s OK

I've been writing a fair bit of code lately, and decided to take a break and do some documentation.  I decided to use Sphinx to autogenerate HTML documentation from python docstrings.

It works pretty well, except I noticed there were key methods that did not show up in the auto-generated documentation.  Comparing them against the methods that appeared properly quickly revealed that somehow methods that had a decorator did not show up.

A search on StackOverflow gave a good description of the problem.  Essentially, Sphinx uses introspection to check function.__name__ and function.__doc__ to pull out the docstring.  A function decorator creates a new function from your code, and the new function has its own __name__ and __doc__.  So in your decorator, you need to ensure that you copy the original function's __name__ and __doc__ to the function created by your decorator.  functools.wraps() simplifies this.

My solution wasn't quite so simple.  I had used a class decorator instead of a function decorator.  Simply copying __name and __doc__ over didn't work, since the class decorator returns a class instead of a function, and Sphinx was looking for functions to document.  It looks like the solution to this is to wrap the class decorator inside a function decorator.  I didn't strictly need to use a class decorator, so I rewrote it as a function decorator and things went along ok.