Могу ли я подавить переменное расширение в документации Sphinx?

Question

В моем коде я имею

X_DEFAULT = ['a', 'long', 'list', 'of', 'values', 'that', 'is', 'really', 'ugly', 'to', 'see', 'over', 'and', 'over', 'again', 'every', 'time', 'it', 'is', 'referred', 'to', 'in', 'the', 'documentation'] 

и позже

def some_function(..., x=X_DEFAULT, ...): 

так, что в моей документации сфинкса, используя (например, с использованием .. autofunction:: и т.д.) Я получаю все долгое и громоздкое значение X_DEFAULT расширен в подписи для some_function:

some_function (..., x = ['a', 'long', 'list', 'of', 'values', 'that', 'is', 'really', 'ugly', 'to', ' см. ',' over ',' and ',' over ',' again ', ' every ',' time ',' it ',' is ',' refer ',' to ',' in ',' », 'документации'], ...)

есть ли способ, чтобы подавить эту замену в создаваемой документации, в идеале с обратной ссылкой на определение X_DEFAULT:

some_function ( ..., x = X_DEFAULT, ...)

---

Я знаю, что я могу вручную изменить подпись для каждой функции и метод, который я явно перечислить в качестве аргументов директив документации сфинкса, но это не моя цель здесь. Я также знаю, что я мог бы использовать autodoc_docstring_signature и первую строку docstring, но это создавало бы плохие docstrings, действительно предназначенные для случаев, когда интроспекция терпит неудачу (например, C). Я подозреваю, что есть что-то, что я мог бы сделать в autodoc-process-signature, что может быть адекватным (но не идеальным), хотя я не уверен, как действовать дальше.

Answer 1

Один подход, который будет, например, «возвращать» замену всех значений, которые были определены на уровне модуля как «общедоступные константы» (признанные именами всех шапков без лидирующего подчеркивания), для которых уникальное имя можно найти в модуле, в котором он был определен:

def pretty_signature(app, what, name, obj, options, signature, return_annotation): 
    if what not in ('function', 'method', 'class'): 
     return 

    if signature is None: 
     return 

    import inspect 
    mod = inspect.getmodule(obj) 

    new_sig = signature 
    # Get all-caps names with no leading underscore 
    global_names = [name for name in dir(mod) if name.isupper() if name[0] != '_'] 
    # Get only names of variables with distinct values 
    names_to_replace = [name for name in global_names 
         if [mod.__dict__[n] for n in global_names].count(mod.__dict__[name]) == 1] 
    # Substitute name for value in signature, including quotes in a string value 
    for var_name in names_to_replace: 
     var_value = mod.__dict__[var_name] 
     value_string = str(var_value) if type(var_value) is not str else "'{0}'".format(var_value) 
     new_sig = new_sig.replace(value_string, var_name) 

    return new_sig, return_annotation 

def setup(app): 
    app.connect('autodoc-process-signature', pretty_signature) 

---

в качестве альтернативы можно просто взять строку документации непосредственно из источника:

import inspect 
import re 

def pretty_signature(app, what, name, obj, options, signature, return_annotation): 
    """Prevent substitution of values for names in signatures by preserving source text.""" 
    if what not in ('function', 'method', 'class') or signature is None: 
     return 

    new_sig = signature 
    if inspect.isfunction(obj) or inspect.isclass(obj) or inspect.ismethod(obj): 
     sig_obj = obj if not inspect.isclass(obj) else obj.__init__ 
     sig_re = '\((self|cls)?,?\s*(.*?)\)\:' 
     new_sig = ' '.join(re.search(sig_re, inspect.getsource(sig_obj), re.S).group(2).replace('\n', '').split()) 
     new_sig = '(' + new_sig + ')' 

    return new_sig, return_annotation