python - Python 2 和 3 中 unicode/str 参数的正确文档字符串是什么

Question

我有一个方法在 Python 2 中接受 unicode 参数，但在 Python 3 中它接受 str。
我想知道我应该如何为这个函数编写 sphinx 文档字符串:
:param unicode text: 或 :param str text: 或 Python 2 和 Python 3 的单独文档？

例子:

def myfunction(text):
    """Do something with text
    :param unicode text: Must be unicode
    :rtype: unicode
    :raises TypeError: If text is not a unicode
    """
    if PY2 and not isinstance(text, unicode):
        raise TypeError("Argument 'text' must be unicode")
    ...
    return text

Answer 1

我认为没有比 six.text_type 更简单的方法了.

但最重要的是: - 请仔细检查你是否真的需要 unicode 而不是 basestring，这看起来不是 pythonic - 如果你正在迁移到 PY3 并且这是兼容性问题 - 只需使用 str 和 PY3 的文档 - 为 PY3 编写类型并澄清描述中的差异。 Docstrings 是 100% 供人类使用的，只是想一想它是否更容易在极少数情况下阅读 1 个注释或每次都破译奇怪的兼容性类型