Feature Request: safe_json() Method for Requests Library

[nh916]

Description

I would like to propose the addition of a safe_json() method to the requests.Response object. This method would attempt to return the response content as JSON if it is JSON. If the response content is not JSON, it would return the text content. If the response content is neither JSON nor text, it would return None.

Rationale

When working with HTTP responses, it is common to handle different content types. A response might contain JSON, plain text, or even be empty. Currently, developers have to manually write error handling to safely parse JSON responses while falling back to text if JSON parsing fails. This can lead to repetitive boilerplate code and potential bugs.

try:
    content = response.json()
except ValueError:
    content = response.text if response.text else None

A safe_json() method would streamline this process, providing a convenient and reliable way to handle different response content types. This would enhance the usability of the requests library and improve developer productivity.

Proposed Solution

from typing import Any, Union, Optional

class Response:
    # Existing methods...

    def safe_json(self) -> Optional[Union[dict, list, str]]:
        """
        Attempt to parse the response content as JSON.

        Returns:
            Optional[Union[dict, list, str]]: The parsed JSON content if the response is JSON.
            The text content if the response is not JSON.
            None if the response content is neither JSON nor text.
        """
        try:
            return self.json()
        except ValueError:
            if self.text:
                return self.text
            return None

Possible Benefits:

• Reduction in boilerplate code for error handling when parsing JSON.
• Provides a clear and consistent way to handle different types of response content.
• Improves code readability and maintainability.

Thank you for considering this feature request

[github-actions]

As described in the template, Requests is not accepting feature requests