Рубрики
Без рубрики

Docstrings в Python: Easy Reference

Docstrings в Python являются строковыми литералами, которые происходят в качестве первого утверждения в модуле, функции, классе или определении метода. Использование Docstrings вы можете

Автор оригинала: Pankaj Kumar.

Docstrings в Python являются строковыми литералами, которые происходят в качестве первого утверждения в модуле, функции, классе или определении метода. Использование Docstrings Вы можете предоставить документацию для кода, который вы пишете.

Каждая библиотека Python поставляется с надлежащей документацией. В этом руководстве мы узнаем, как получить доступ к этим DOCStrings и как установить DocStrings для ваших собственных функций. Давайте начнем.

Сначала мы узнаем, как получить доступ к Docstrings Python Modules.

Как получить доступ к Docstrings в Python?

Существует два метода для доступа к DOCStrings. Эти:

  • Использование помощь()
  • Использование .__ DOC__

Давайте посмотрим, как использовать их.

Метод 1: Использование справки () для доступа к Docstrings Python Module

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

import matplotlib
help(matplotlib)

Выход:

Вы также можете использовать помощь, чтобы получить DocString для определенного пакета.

help(matplotlib.axes)

Выход:

Точно так же вы также можете получить доступ к Docstrings определенной функции под MATPLOTLIB.

help(matplotlib.pyplot.axis)

Выход:

Метод 2: Используя .__ DOC__ Метод для доступа к модулям Docstrings

Вы можете получить доступ к Docstring модуля, используя .__ doc__ Метод:

import matplotlib
print(matplotlib.__doc__)

Выход:

Как создать свои собственные Docstrings в Python?

В этом разделе мы узнаем, как добавить DocStrings в функции, которые мы пишем в Python. Позже мы будем использовать два метода, обсуждаемыми выше для доступа к этим DocStrings.

Вы можете либо дать однострочная DOCSTRING или Многострочная DocString к вашей функции.

Однострочные DocStrings обычно содержат сводку того, что делает функция.

Многострочные DocStrings состоят из:

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

Docstrings написаны в соответствии с PEP 257 Конвенции Docstring Отказ

Как написать однострочную Docstring в Python?

Давайте напишем простую функцию и добавьте его DOCSTRING.

def sample_func():

  ''' this function prints Hello World. '''

  print("Hello World")
  return

Попробуем доступ к доступе к Docstring с двумя методами, которые мы обсуждали.

def sample_func():

  ''' this function prints Hello World. '''

  print("Hello World")
  return

print("Method-1:-")
help(sample_func)
print("Method-2:-")
print(sample_func.__doc__)

Выход:

Method-1:-
Help on function sample_func in module __main__:

sample_func()
    this function prints Hello World.

Method-2:-
 this function prints Hello World.

Как написать многострочные Docstrings в Python?

Давайте напишем многострочную Docstring для нашей функции. Общая конвенция состоит в том, чтобы оставить линию пробел после каждой строки в DOCSTRING.

def sample_func():

  ''' 
  this function prints Hello World. 
  
      This is a multi-line docstring.

      You can add a more descriptive help section 
      for your function here.
      
  '''

  print("Hello World")
  return

Попробуем доступ к доступе к DocString с двумя методами, которые мы узнали.

def sample_func():

  ''' 
  this function prints Hello World. 
  
      This is a multi-line docstring.

      You can add a more descriptive help section 
      for your function here.
      
  '''

  print("Hello World")
  return

print("Mehtod-1 :-")
help(sample_func)
print("Mehtod-2 :-")
print(sample_func.__doc__)

Выход:

Mehtod-1 :-
Help on function sample_func in module __main__:

sample_func()
    this function prints Hello World. 
    
        This is a multi-line docstring.
    
        You can add a more descriptive help section 
        for your function here.

Mehtod-2 :-
 
  this function prints Hello World. 
  
      This is a multi-line docstring.

      You can add a more descriptive help section 
      for your function here.

Вы также можете использовать двойные кавычки («) вместо одиночных кавычек (‘).

def sample_func():

  """
  this function prints Hello World. 
  
      This is a multi-line docstring.

      You can add a more descriptive help section 
      for your function here.
      
  """

  print("Hello World")
  return

print("Mehtod-1 :-")
help(sample_func)
print("Mehtod-2 :-")
print(sample_func.__doc__)

Выход:

Mehtod-1 :-
Help on function sample_func in module __main__:

sample_func()
    this function prints Hello World. 
    
        This is a multi-line docstring.
    
        You can add a more descriptive help section 
        for your function here.

Mehtod-2 :-

  this function prints Hello World. 
  
      This is a multi-line docstring.

      You can add a more descriptive help section 
      for your function here.

Заключение

Это руководство было о Docstrings в Python. Мы узнаем, как получить доступ к DocString с помощью справки и .__ DOC__ и как создавать DocStrings в функции. Надеюсь, вы веселились с нами!

Читайте ещё по теме: