### Configuring pydocstyle in Pre-commit

Source: https://context7.com/pycqa/pep257/llms.txt

Provides configuration examples for integrating pydocstyle into a .pre-commit-config.yaml file, including argument customization.

```yaml
repos:
  - repo: https://github.com/pycqa/pydocstyle
    rev: 6.3.0
    hooks:
      - id: pydocstyle
        args: [--convention=google, --add-ignore=D100,D104]
```

--------------------------------

### Install pydocstyle

Source: https://context7.com/pycqa/pep257/llms.txt

Install the pydocstyle package using pip. Includes an optional dependency for TOML configuration support.

```bash
pip install pydocstyle
pip install pydocstyle[toml]
```

--------------------------------

### Install pydocstyle using pip

Source: https://github.com/pycqa/pep257/blob/master/docs/snippets/install.md

This snippet shows the command to install the pydocstyle package using pip, a common Python package installer. It requires pip to be installed on the system.

```bash
pip install pydocstyle
```

--------------------------------

### Resolving Missing Docstring Violations (D1xx)

Source: https://context7.com/pycqa/pep257/llms.txt

Examples of proper docstring placement for modules, classes, methods, and functions to satisfy D1xx requirements.

```python
class DataProcessor:
    """Process and transform data from various sources."""
    def add(self, a, b):
        """Add two numbers and return the result."""
        return a + b
```

--------------------------------

### Run pydocstyle directly from source

Source: https://github.com/pycqa/pep257/blob/master/docs/snippets/install.md

This snippet demonstrates how to execute the pydocstyle script directly from its source file. This method is useful if you prefer not to install the package system-wide or are developing the tool.

```bash
python pydocstyle.py
```

--------------------------------

### Configure pydocstyle via ini file

Source: https://github.com/pycqa/pep257/blob/master/docs/snippets/config.md

Example of a standard pydocstyle configuration file. This snippet disables inheritance and defines specific ignore rules and file matching patterns.

```ini
[pydocstyle]
inherit = false
ignore = D100,D203,D405
match = .*\.py
```

--------------------------------

### Python Docstring: Missing Argument Descriptions (Google/NumPy Style)

Source: https://context7.com/pycqa/pep257/llms.txt

Demonstrates the D417 rule for missing argument descriptions in Google or NumPy style docstrings. This example includes correctly documented arguments.

```python
def documented_args(name, age):
    """Create a new user profile.

    Args:
        name: The user's full name.
        age: The user's age in years.
    """
    pass
```

--------------------------------

### Python Docstring: No Function Signature in First Line

Source: https://context7.com/pycqa/pep257/llms.txt

Demonstrates the D402 rule where the first line of a docstring should not be a function signature. This example shows a correct docstring.

```python
def no_signature(x, y):
    """Add two numbers together."""  # Good
    # NOT: """no_signature(x, y)"""
    pass
```

--------------------------------

### Resolving Content and Style Violations (D4xx)

Source: https://context7.com/pycqa/pep257/llms.txt

Examples of enforcing imperative mood and proper punctuation in docstring summaries.

```python
def imperative():
    """Calculate the total."""  # Imperative mood
    pass

def question_ending():
    """Is the value within range?"""  # Proper punctuation
    pass
```

--------------------------------

### Python Docstring: First Word Capitalized

Source: https://context7.com/pycqa/pep257/llms.txt

Illustrates the D403 rule requiring the first word of a docstring to be capitalized. This example shows a correctly capitalized docstring.

```python
def capitalized():
    """Return the processed value."""  # Good: "Return" capitalized
    pass
```

--------------------------------

### Python Docstring: First Word Not 'This'

Source: https://context7.com/pycqa/pep257/llms.txt

Shows the D404 rule, which prohibits the first word of a docstring from being 'This'. This example provides a valid docstring.

```python
def not_this():
    """Process the input data."""  # Good
    # NOT: """This function processes..."""
    pass
```

--------------------------------

### Python API: Selecting Error Codes

Source: https://context7.com/pycqa/pep257/llms.txt

Illustrates how to use the `select` parameter within the `check()` function to filter docstring checks for specific error codes or ranges of codes. This allows for targeted validation, such as checking only for missing docstrings (codes starting with 'D1').

```Python
from pydocstyle import check

# Check only for specific error codes
for error in check(['mymodule.py'], select=['D100', 'D101', 'D102']):
    print(f"{error.code}: {error.message}")

# Check for all errors starting with D1 (missing docstrings)
for error in check(['mymodule.py'], select=['D100', 'D101', 'D102', 'D103', 'D104', 'D105', 'D106', 'D107']):
    print(f"{error.code}: {error.message}")
```

--------------------------------

### Python API: Using Conventions

Source: https://context7.com/pycqa/pep257/llms.txt

Explains how to apply different docstring conventions (like PEP 257, NumPy, or Google) using the `select` parameter with predefined convention sets. It also covers customizing conventions by adding or removing specific error codes to tailor the checks to project-specific requirements.

```Python
from pydocstyle import check
from pydocstyle.violations import conventions

# Check using PEP 257 convention (default)
for error in check(['mymodule.py'], select=conventions.pep257):
    print(f"{error.code}: {error.message}")

# Check using NumPy convention
for error in check(['mymodule.py'], select=conventions.numpy):
    print(f"{error.code}: {error.message}")

# Check using Google convention
for error in check(['mymodule.py'], select=conventions.google):
    print(f"{error.code}: {error.message}")

# Customize a convention by adding/removing codes
custom_convention = conventions.google | {'D404'}  # Add D404
custom_convention = conventions.google - {'D415'}  # Remove D415
for error in check(['mymodule.py'], select=custom_convention):
    print(f"{error.code}: {error.message}")
```

--------------------------------

### Accessing pydocstyle Error Details

Source: https://context7.com/pycqa/pep257/llms.txt

Demonstrates how to programmatically check files and access detailed error metadata including filenames, line numbers, and source context.

```python
from pydocstyle import check
from pydocstyle.violations import Error

Error.explain = True
Error.source = True

for error in check(['mymodule.py']):
    print(f"File: {error.filename}")
    print(f"Line: {error.line}")
    print(f"Code: {error.code}")
    print(f"Message: {error.message}")
    print(f"Source:\n{error.lines}")
    print(f"Explanation: {error.explanation}")
```

--------------------------------

### Resolving Whitespace and Formatting Violations (D2xx)

Source: https://context7.com/pycqa/pep257/llms.txt

Demonstrates correct formatting for one-line and multi-line docstrings, including blank line rules and closing quote placement.

```python
def documented():
    """Short summary line.

    Longer description that explains the function
    in more detail.
    """
    pass
```

--------------------------------

### Python API: ConventionChecker Class

Source: https://context7.com/pycqa/pep257/llms.txt

Introduces the `ConventionChecker` class for more granular control over source code analysis. It demonstrates how to instantiate the checker and use its `check_source()` method to validate docstrings directly from a string, providing options to customize the checking behavior.

```Python
from pydocstyle.checker import ConventionChecker
import re

source_code = '''
def greet(name):
    """says hello to the user"""
    print(f"Hello, {name}!")

class Calculator:
    def add(self, a, b):
        return a + b
'''

checker = ConventionChecker()

# Check source code directly
for error in checker.check_source(
    source=source_code,
    filename='example.py',
    ignore_decorators=None,
    property_decorators=None,
    ignore_inline_noqa=False,
    ignore_self_only_init=False
):
    print(f"Line {error.line}: {error.code} - {error.message}")

# Example output:
# Line 2: D401 - First line should be in imperative mood (perhaps 'Say', not 'says')
# Line 2: D400 - First line should end with a period (not 'r')
# Line 7: D101 - Missing docstring in public class
# Line 8: D102 - Missing docstring in public method
```

--------------------------------

### Run pydocstyle CLI

Source: https://context7.com/pycqa/pep257/llms.txt

Execute pydocstyle on files or directories to identify docstring violations. Supports various flags for convention selection, error filtering, and output formatting.

```bash
pydocstyle mymodule.py
pydocstyle src/
pydocstyle --convention=numpy src/
pydocstyle --select=D1,D2 src/
pydocstyle --explain --source src/
```

--------------------------------

### Python API: Basic File Check

Source: https://context7.com/pycqa/pep257/llms.txt

Demonstrates how to use the `check()` function from the pydocstyle library to programmatically check single or multiple Python files for docstring violations according to PEP 257 conventions. It iterates through the returned errors, printing details like filename, line number, error code, and message.

```Python
from pydocstyle import check

# Check a single file with default PEP 257 convention
for error in check(['mymodule.py']):
    print(f"{error.filename}:{error.line} - {error.code}: {error.message}")

# Check multiple files
for error in check(['module1.py', 'module2.py', 'src/module3.py']):
    print(error)

# Example output:
# mymodule.py:10 in public function `calculate`:
#         D103: Missing docstring in public function
```

--------------------------------

### Retrieving Error Registry and Conventions

Source: https://context7.com/pycqa/pep257/llms.txt

Shows how to query the ErrorRegistry to list all available violation codes, group them by category, and inspect convention-specific sets.

```python
from pydocstyle.violations import ErrorRegistry, conventions

all_codes = list(ErrorRegistry.get_error_codes())
for group in ErrorRegistry.groups:
    print(f"\n{group.name} ({group.prefix}xx):")
    for error in group.errors:
        print(f"  {error.code}: {error.short_desc}")

print(f"PEP 257 codes: {len(conventions.pep257)}")
```

--------------------------------

### Integrate pydocstyle with pre-commit

Source: https://github.com/pycqa/pep257/blob/master/docs/usage.md

Configuration for adding pydocstyle as a hook in the .pre-commit-config.yaml file, including optional command-line arguments.

```yaml
-   repo: https://github.com/pycqa/pydocstyle
    rev: 0.0.0.dev0
    hooks:
    -   id: pydocstyle

- id: pydocstyle
  args:
  - --ignore=D100,D203,D405
  - |-
          --select=
          D101,
          D2
```

--------------------------------

### Python API: Advanced Options

Source: https://context7.com/pycqa/pep257/llms.txt

Details advanced configuration options for the `check()` function, including ignoring functions with specific decorators using regex, disabling inline `# noqa` comment processing, and ignoring `__init__` methods that only accept `self`. These options provide finer control over the docstring validation process.

```Python
import re
from pydocstyle import check

# Ignore functions decorated with specific decorators
ignore_decorators_pattern = re.compile(r'property|abstractmethod|overload')
for error in check(
    ['mymodule.py'],
    ignore_decorators=ignore_decorators_pattern
):
    print(error)

# Disable inline # noqa comment processing
for error in check(
    ['mymodule.py'],
    ignore_inline_noqa=True
):
    print(error)

# Ignore __init__ methods that only have 'self' parameter
for error in check(
    ['mymodule.py'],
    ignore_self_only_init=True
):
    print(error)

# Combine multiple options
for error in check(
    ['mymodule.py'],
    select=['D100', 'D101', 'D102', 'D103'],
    ignore_decorators=re.compile(r'property'),
    ignore_self_only_init=True,
    ignore_inline_noqa=False
):
    print(f"{error.filename}:{error.line} {error.code}: {error.message}")
```

--------------------------------

### Run pydocstyle on a Python file

Source: https://github.com/pycqa/pep257/blob/master/README.rst

Executes the pydocstyle linter against a specific Python file to identify violations of docstring conventions. The output displays the file path, line number, and specific error codes found.

```bash
pydocstyle test.py
```

--------------------------------

### Function: check()

Source: https://context7.com/pycqa/pep257/llms.txt

The primary entry point for checking files for docstring violations. It supports single or multiple file paths and returns a generator of error objects.

```APIDOC
## Python API: check()

### Description
Programmatically check files for docstring violations using the pydocstyle library.

### Method
Function Call

### Parameters
#### Arguments
- **filenames** (list) - Required - A list of file paths to check.
- **select** (list) - Optional - A list of error codes to include.
- **ignore** (list) - Optional - A list of error codes to exclude.
- **ignore_decorators** (pattern) - Optional - Regex pattern for decorators to ignore.
- **ignore_inline_noqa** (bool) - Optional - Whether to disable # noqa processing.
- **ignore_self_only_init** (bool) - Optional - Whether to ignore __init__ methods with only 'self'.

### Request Example
from pydocstyle import check
for error in check(['mymodule.py'], select=['D100', 'D101']):
    print(error.message)

### Response
Returns a generator yielding `pydocstyle.violations.Error` objects.
```

--------------------------------

### Class: ConventionChecker

Source: https://context7.com/pycqa/pep257/llms.txt

Provides advanced control for checking source code strings directly instead of files.

```APIDOC
## Python API: ConventionChecker

### Description
Use the ConventionChecker class for more granular control over source checking, particularly useful for dynamic code analysis.

### Method
Class Method: check_source

### Parameters
#### Arguments
- **source** (str) - Required - The source code string to analyze.
- **filename** (str) - Required - The filename associated with the source.

### Request Example
from pydocstyle.checker import ConventionChecker
checker = ConventionChecker()
for error in checker.check_source(source=my_code, filename='test.py'):
    print(error.code)

### Response
Returns a generator yielding `pydocstyle.violations.Error` objects.
```

--------------------------------

### Skip Specific pydocstyle Check via Inline Comment

Source: https://github.com/pycqa/pep257/blob/master/docs/snippets/in_file.md

Demonstrates how to use the # noqa comment to ignore a specific pydocstyle rule (D400) for a function docstring. This allows for intentional deviations from style guidelines in specific code blocks.

```python
def bad_function():  # noqa: D400
    """Omit a period in the docstring as an exception"""
    pass
```

--------------------------------

### Python API: Ignoring Error Codes

Source: https://context7.com/pycqa/pep257/llms.txt

Shows how to use the `ignore` parameter in the `check()` function to exclude specific error codes from the docstring validation process. This is useful for cases where certain violations are intentionally allowed or not relevant. It also demonstrates using set operations on predefined conventions to create custom ignore lists.

```Python
from pydocstyle import check
from pydocstyle.violations import conventions

# Ignore specific error codes
for error in check(['mymodule.py'], ignore=['D100', 'D104']):
    print(f"{error.code}: {error.message}")

# Use a convention as base and remove specific errors
ignore_codes = conventions.pep257 - {'D100', 'D101'}
for error in check(['mymodule.py'], ignore=ignore_codes):
    print(f"{error.code}: {error.message}")
```

--------------------------------

### Disable Checks with Inline Comments

Source: https://context7.com/pycqa/pep257/llms.txt

Use noqa comments within Python code to skip specific docstring checks for individual functions or methods.

```python
def function_without_docstring():  # noqa
    pass

def function_with_missing_period():  # noqa: D400
    """This docstring intentionally omits a period"""
    pass
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.