11

Conforme a PEP 257, tem-se:

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

Isto é, a docstring é uma string literal que é a primeira instrução de um módulo, classe ou função, que ficará acessível pelo campo __doc__ do objeto.

def hello():
    'Exibe uma saudação'
    print('Hello')

print(hello.__doc__)  # Exibe uma saudação

Veja funcionando no Repl.it | GitHub GIST

Mas se tentarmos utilizar uma f-string, com formatação, o valor de __doc__ será None.

__author__ = 'Anderson Carlos Woss'

def hello():
    f'Autor: {__author__}'
    print('Hello')

print(hello.__doc__)  # None

Veja funcionando no Repl.it | GitHub GIST

Por que as f-string não podem ser utilizadas como docstring?

4
  • 1
    Porque o Guido mandou! Agora que ele não manda mais, pode usar sim! :P :D Eu acredito ser uma limitação porque ele só consegue pegar um valor constante. Quando está usando interpolação aquilo é uma ação a ser executada no momento da execução para dar um resultado. Vale como resposta se elaborar um pouco mais?
    – Maniero
    Commented 17/08/2018 às 18:12
  • Vale, principalmente se tiver fontes. O caminho é esse mesmo. A f-string deixa de ser literal por precisar tratar a interpolação e, por definição, não pode ser usada como docstring.
    – Woss
    Commented 17/08/2018 às 18:14
  • Acho que sim, achei fundamentação :)
    – Maniero
    Commented 17/08/2018 às 18:17
  • Até porque a docstring é gerada em tempo de "compilação", não tempo de execução, então como garantiria o valor da variável? Nesse caso possui valor, mas imagina usar um parâmetro dentro da docstrings...
    – Woss
    Commented 17/08/2018 às 18:19

2 Respostas 2

5

Porque a f-string deixa de ser literal e, por definição, deixa se ser uma candidata a ser docstring.

Também pelo fato que a docstring é gerada em tempo de compilação, quando gerado o byte-code que será interpretado - como o Maniero comento em sua resposta, isso foi uma escolha de projeto; eles poderiam fazer o valor ser avaliado em tempo de execução, mas não viram motivos para tal. Assim, como garantir o valor dos objetos que serão interpolados? No caso da pergunta, a interpolação ocorre apenas com uma variável global e poderia gerar a docstring "Autor: Anderson Carlos Woss", mas e se eu fizer em algum outro ponto do código __author__ = 'Foo', isso deveria alterar a docstring? Isso piora se considerarmos que poderíamos adicionar o valor de um parâmetro da função na docstring:

def hello(name):
    f'Saudação para {name}'
    print(f'Hello, {name}')

Neste caso, qual seria o valor de hello.__doc__? Uma opção seria considerar a string sem formatação como docstring, mas, novamente, isso foi uma escolha de projeto. Que sentido teria uma docstring com o valor Autor: {__author__}?

Quanto a não ser mais uma string literal, veja a diferença entre os opcodes gerados para uma string normal e uma f-string.

String normal

>>> print(dis.dis('"Hello"'))
  1           0 LOAD_CONST               0 ('Hello')
              2 RETURN_VALUE
None

F-String

>>> print(dis.dis('f"Hello {name}"'))
  1           0 LOAD_CONST               0 ('Hello ')
              2 LOAD_NAME                0 (name)
              4 FORMAT_VALUE             0
              6 BUILD_STRING             2
              8 RETURN_VALUE
None

Os passos extras, para formatar e construir a string final fazem com que a f-string deixe de ser apenas um valor literal e precise desta execução. Por exemplo, veja o opcode gerado quando é utilizado uma string literal como docstring:

  2           0 LOAD_CONST               0 ('Hello world')
              2 STORE_NAME               0 (__doc__)

  3           4 LOAD_NAME                1 (print)
              6 LOAD_CONST               1 ('Hello')
              8 CALL_FUNCTION            1
             10 POP_TOP
             12 LOAD_CONST               2 (None)
             14 RETURN_VALUE
None

Perceba que ele armazena a string dentro do objeto __doc__, seja ele do módulo, classe ou função. Porém, ao informar uma f-string, o resultado é:

  2           0 LOAD_CONST               0 ('Hello ')
              2 LOAD_NAME                0 (name)
              4 FORMAT_VALUE             0
              6 BUILD_STRING             2
              8 POP_TOP

  3          10 LOAD_NAME                1 (print)
             12 LOAD_CONST               1 ('Hello')
             14 CALL_FUNCTION            1
             16 POP_TOP
             18 LOAD_CONST               2 (None)
             20 RETURN_VALUE
None

Ou seja, o interpretador irá avaliar a f-string, efetuar a interpolação dos valores e retornar a string final que, como não será mais uma docstring, será uma string avulsa no código e, portanto, descartada. Como não é informada uma string literal, a função acaba ficando sem uma docstring, por isso retorna None.

3

O mecanismo da docstring deve ser muito simples, só ter uma valor constante que ficar armazenado em algum lugar e que se invocado ele é trazido à tona porque quem precisou dele. Não foi intuito da linguagem prover um mecanismo mais sofisticado. A f-string é mais sofisticada, ela tem execução de código para chegar em um resultado, porque a interpolação não ocorre magicamente só porque a sintaxe parece indicar isto, há a chamada de uma função que concatena adequadamente os textos necessários.

Isto pode ser confirmado quando abriram um bug na documentação que foi acatado para indicar que não pode mesmo.

Poderiam ter optado por fazer uma mecanismo mais sofisticado que permitisse resolver em tempo de execução, nem seria muito fora da filosofia da linguagem, mas em geral não compensa, eu até questiono a necessidade deste tip ode coisa na forma atual, até porque a linguagem já possui forma mais sofisticada de fazer isto, apesar de exigir mais esforço. E até para fazer exatamente isto manualmente é bem simples.

3
  • 1
    "Poderiam ter optado por fazer uma mecanismo mais sofisticado que permitisse resolver em tempo de execução," - Não poderiam não: uma fstring depende de ser executada, ou seja - só tem seu valor renderizado quando a função é chamada. Uma docstring se torna um atributo do objeto função - independete da função jamais ser chamada ou não - ou seja, tem que ser conhecida "de fora". F-strings como docstrings não são uma opção, na verdade, sequer fazem sentido.
    – jsbueno
    Commented 17/08/2018 às 21:51
  • Poderiam, mas está fora do escopo explicar como fazer, eu sei como solucionar isso, pode até não ser do jeito que se espera, e claro, como eu disse não compensa o esforço porque não haverá um ganho real, não é algo que seja necessário, e não sei se está dentro que que propuseram fazer, mas o importante é que poderiam sim.
    – Maniero
    Commented 17/08/2018 às 21:58
  • 1
    não poderiam não. :-) não sem destruir a linguagem. é Python, não uma linguagem hobbista que não se importaria em destruir a consistência em troca de uma feature que nem seria tão grande coisa. Em particular, não existe um frame da função com suas variáveis locais quando o objeto função é montado. Outro, que o código dentro de fstrings pode desencdear efeitos colaterais, já que pode chamar funções - você teria algo dentro do corpo de uma função sendo desencadeado quando um módulo é simplesmente importado: isso não seria mais Python.
    – jsbueno
    Commented 18/08/2018 às 2:52

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .