Introduction to pydocstyle

pydocstyle is a static analysis tool for checking compliance with Python docstring conventions. It helps ensure that your docstrings are well-formatted and adhere to specified guidelines, making your code more readable and maintainable.

Installation

  
  pip install pydocstyle
  

Basic Usage

  
  pydocstyle target_directory_or_file.py
  

Configuring pydocstyle

You can configure pydocstyle by creating a setup.cfg or tox.ini file in your project. Here is an example configuration:

  
  [tool:pytest]
  addopts = --pydocstyle

  [tool:pydocstyle]
  ignore = D203,D212
  

Understanding pydocstyle Error Codes

pydocstyle provides various error codes to indicate different types of docstring issues. Here are some examples:

  
  D100: Missing docstring in public module
  D101: Missing docstring in public class
  D102: Missing docstring in public method
  D103: Missing docstring in public function
  D104: Missing docstring in public package
  D105: Missing docstring in magic method
  D200: One-line docstring should fit on one line with quotes
  D201: No blank lines allowed before function docstring
  D203: 1 blank line required before class docstring
  D204: 1 blank line required after class docstring
  D205: 1 blank line required between summary line and description
  D210: No whitespaces allowed before docstring
  D211: No blank lines allowed in docstring
  

Example Project Using pydocstyle

Consider the following simple Python module:

  
  def add(a, b):
      \"\"\"Add two numbers.

      Args:
          a (int): The first number.
          b (int): The second number.

      Returns:
          int: The sum of the two numbers.
      \"\"\"
      return a + b

  def subtract(a, b):
      \"\"\"Subtract two numbers.

      Args:
          a (int): The number to subtract from.
          b (int): The number to be subtracted.

      Returns:
          int: The result of the subtraction.
      \"\"\"
      return a - b
  

To check the docstring format of this module, run:

  
  pydocstyle your_module.py
  

The output will indicate any issues with the docstrings, helping you maintain clean and consistent documentation within your codebase.

Hash: 964d584b85430a3ed81bcb8a0aaeaa7398324063a4f18845363b759dfc983bc0