如何在Python中記錄模塊常量？

我有一個模塊，errors.py其中定義了幾個全局常量（注意：我知道Python沒有常量，但我已經按照慣例使用大寫定義了它們）。如何在Python中記錄模塊常量？

"""Indicates some unknown error.""" 
API_ERROR = 1 

"""Indicates that the request was bad in some way.""" 
BAD_REQUEST = 2 

"""Indicates that the request is missing required parameters.""" 
MISSING_PARAMS = 3

使用reStructuredText如何記錄這些常量？正如你所看到的，我已經列出了一個文檔字符串，但是我還沒有找到任何指示這樣做的文檔，我只是將它作爲一個猜測。

來源

2013-11-26 skyler

你是什麼意思？「我如何記錄這些常量？」。添加註釋（或您的案例中的字符串）已經是一種文檔形式。你在問如何讓sphinx-autodoc識別你的內部文檔並將其顯示在sphinx的輸出中？ – mgilson

不幸的是，變量（和常量）沒有文檔字符串。畢竟，該變量只是一個整數的名稱，並且您不希望將文檔字符串附加到數字1上，就像您對函數或類對象的方式一樣。

如果你看stdlib中的幾乎任何模塊，如pickle，你會看到他們使用的唯一文檔是註釋。是的，這意味着help(pickle)只能說明這一點：

DATA 
    APPEND = b'a' 
    APPENDS = b'e' 
    …

...完全忽視了意見。如果您希望自己的文檔顯示在內置幫助中，則必須將它們添加到模塊的文檔字符串中，這並不完全理想。

但獅身人面像可以做比內置的幫助更多的東西。您可以對其進行配置以提取常量上的註釋，或者使用autodata半自動地進行評論。例如：

#: Indicates some unknown error. 
API_ERROR = 1

多以前#:線的任何賦值語句，或聲明的右單#:評論，有效地開展工作作爲對象的文檔字符串由車博士拿起相同。其中包括處理內聯rST，併爲變量名自動生成rST頭;沒有什麼額外的工作要做。

作爲一個側面說明，你可能要考慮使用替代enum像這樣單獨的常量。如果你沒有使用Python 3.4（你可能還沒有...），那麼3.2 +或flufl.enum就有一個backport.enum包（它不是完全相同，但它是相似的，因爲它是stdlib模塊的主要靈感）爲2.6+。

枚舉實例（不flufl.enum，但STDLIB /反向移植版），甚至可以有文檔字符串：

class MyErrors(enum.Enum): 
    """Indicates some unknown error.""" 
    API_ERROR = 1 

    """Indicates that the request was bad in some way.""" 
    BAD_REQUEST = 2 

    """Indicates that the request is missing required parameters.""" 
    MISSING_PARAMS = 3

雖然他們遺憾的是不help(MyErrors.MISSING_PARAMS)露面，他們是文檔字符串是獅身人面像車博士可以拿起。

來源

2013-11-26 20:21:12 abarnert

我想你在這裏運氣不好。

Python不直接支持變量docstrings：沒有屬性可以附加到變量並交互檢索像模塊，類和函數的__doc__屬性。

Source。

來源

2013-11-26 20:20:06 Johnsyweb

但是，如果OP只是爲了獅身人面像而將它們記錄下來，我相信epydoc使用的'＃：'在sphinx解析器中被重用。 – mgilson

@mgilson：啊，那麼也許鏈接的文檔將幫助☺︎ – Johnsyweb

您可以使用散列+冒號來記錄屬性（類或模塊級別）。

#: Use this content as input for moo to do bar 
    MY_CONSTANT = "foo"

這將有所回升一些文件生成器。

的例子在這裏，找不到一個更好的Sphinx document module properties

來源

2013-11-26 20:30:32

如果你把一個字符串變量後，再獅身人面像將它撿起來作爲變量的文檔。我知道這是有效的，因爲我在各地都做到了。像這樣：

FOO = 1 
""" 
Constant signifying foo. 

Blah blah blah... 
""" # pylint: disable=W0105

pylint指令告訴pylint避免將文檔標記爲無效的語句。

來源

2013-11-26 23:57:32 Louis

，你可以使用這個新的註釋=> .. autodata :: FOO ：annotation：...參見http://sphinx-doc.org/ext /autodoc.html#directive-autoattribute – macm

這是一個較老的問題，但我注意到相關的答案不見了。

或者您可以通過.. py:data::在模塊的文檔字符串中添加常量的說明。通過這種方式，文檔也可以通過交互式幫助獲得。獅身人面像將很好地渲染。

""" 
Docstring for my module. 

.. data:: API_ERROR 

    Indicates some unknown error. 

.. data:: BAD_REQUEST 

    Indicates that the request was bad in some way. 

.. data:: MISSING_PARAMS 

    Indicates that the request is missing required parameters. 
"""

來源

2014-11-11 10:59:15

如何在Python中記錄模塊常量？

回答

相關問題