Изменить положение строки doc в коде Python

Question

Ну, я люблю Python, но нахожу в основном две вещи, которые раздражают: self и docstrings ниже деклараций.

Что я хотел бы знать, как я могу иметь свои докстроны перед декларациями в моем коде? Что-то вроде:

"""Class docstring""" 
class MyClass(object): 
    "Method documentation" 
    def my_method(self): 
     pass 

Возможно, используя какой-то декоратор?

Answer 1

можно написать декоратор, который устанавливает __doc__ свойство:

def doc(docstr): 
    def deco(f): 
     f.__doc__ = docstr 
     return f 
    return deco 

Это будет работать для функций и классов в старом стиле, но не для новых классов, так как атрибут __doc__ классов нового стиля доступен только для чтения (если вы не используете метаклассы, добавляя еще большую сложность для очень небольшого выигрыша).

В любом случае я бы рекомендовал не использовать такой декоратор. Просто придерживайтесь обычных конвенций. Таким образом, товарищи разработчики сразу поймет, что это строка документации, инструменты синтаксического анализа исходного кода строки документации будет работать правильно и т.д.

Edit: Чтобы охватывать классы нового стиля, вы могли бы использовать эту реализацию:

def doc(docstr): 
    def deco(f): 
     if isinstance(f, type): 
      d = vars(f).copy() 
      d["__doc__"] = docstr 
      return type(f.__name__, f.__bases__, d) 
     f.__doc__ = docstr 
     return f 
    return deco 

С __doc__ доступен только для чтения, нам необходимо создать объект нового типа с требуемой документацией. Для простоты я не рассматриваю пользовательские метаклассы (если вы хотите, замените type на f.__class__ в приведенном выше коде).

Опять же, я не рекомендую использовать этот декоратор.

Answer 2

Это не сработает. Докстрина, по определению, является строкой в ​​строке после объявления.

Если вы действительно хотите сделать это с помощью декоратора, вы можете создать декоратор, который устанавливает свойство __doc__ обернутой функции (или класса).

Answer 3

Если вы действительно этого хотите, обязательно.

def doc(text): 
    def w(f): 
    f.__doc__ = text 
    return f 
    return w 

Answer 4

Как вы уже предлагаете в вашем вопросе, вы могли бы сделать что-то следующим образом:

from functools import wraps 

def docstring(docstr): 
    def decorator(cls): 
     @wraps(cls) 
     def wrapper(*args, **kwargs): 
      return cls(*args, **kwargs) 
     wrapper.__doc__ = docstr 
     return wrapper 
    return decorator 

@docstring("""Class docstring""") 
class MyClass(object): 
    def my_method(self): 
     pass 

print MyClass.__doc__ # Class docstring 

Однако я не нахожу это особенно лучше, чем текущий синтаксис.