# Python Warnings Module

The `warnings` module provides a way to issue warning messages to users. Warnings are typically issued in situations where it is useful to alert the user of some condition in a program, where that condition (normally) doesn't warrant raising an exception and terminating the program.

## Importing the Module

```python
import warnings
```

## Issuing Warnings

To issue a warning, use the `warn()` function.

```python
import warnings

def my_function(x):
    if x < 0:
        warnings.warn("Argument is negative", UserWarning)
    return x * x

my_function(-5)
# Output (to stderr):
# UserWarning: Argument is negative
#   warnings.warn("Argument is negative", UserWarning)
```

## Warning Categories

There are several built-in exceptions that represent warning categories. This categorization is useful to be able to filter out groups of warnings.

*   `UserWarning`: Base class for warnings generated by user code.
*   `DeprecationWarning`: Base class for warnings about deprecated features.
*   `SyntaxWarning`: Base class for warnings about dubious syntax.
*   `RuntimeWarning`: Base class for warnings about dubious runtime behavior.
*   `FutureWarning`: Base class for warnings about constructs that will change semantically in the future.
*   `PendingDeprecationWarning`: Base class for warnings about features that will be deprecated in the future.
*   `ImportWarning`: Base class for warnings about probable mistakes in module imports.
*   `UnicodeWarning`: Base class for warnings related to Unicode.
*   `BytesWarning`: Base class for warnings related to bytes and bytearray.
*   `ResourceWarning`: Base class for warnings related to resource usage.

## Filtering Warnings

You can control how warnings are handled using filters.

### `simplefilter()`

The `simplefilter()` function inserts a simple entry into the list of warnings filters.

```python
import warnings

# Ignore all warnings
warnings.simplefilter('ignore')

warnings.warn("This will not be shown")

# Reset to default
warnings.simplefilter('default')
warnings.warn("This will be shown")
```

Common actions:
*   `"error"`: Turn warning into exception.
*   `"ignore"`: Never print matching warnings.
*   `"always"`: Always print matching warnings.
*   `"default"`: Print the first occurrence of matching warnings for each location (module + line number) where the warning is issued.
*   `"module"`: Print the first occurrence of matching warnings for each module where the warning is issued.
*   `"once"`: Print only the first occurrence of matching warnings, regardless of location.

### `filterwarnings()`

For more granular control, use `filterwarnings()`.

```python
# Filter specific category
warnings.filterwarnings('error', category=DeprecationWarning)
```

## Testing Warnings

To test that your code issues warnings correctly, use `catch_warnings` as a context manager.

```python
import warnings

def deprecated_function():
    warnings.warn("This is deprecated", DeprecationWarning)

with warnings.catch_warnings(record=True) as w:
    # Cause all warnings to always be triggered.
    warnings.simplefilter("always")
    
    # Trigger a warning.
    deprecated_function()
    
    # Verify some things
    assert len(w) == 1
    assert issubclass(w[0].category, DeprecationWarning)
    assert "deprecated" in str(w[0].message)
```

[[programming/python/python]]