Skip to content

Add clear best practices for using timeouts in the documentation #7134

@kana44

Description

@kana44

Hi!
Thank you for maintaining the requests library.

While using requests, I noticed that timeouts are very important in real-world applications to avoid hanging requests. Although timeouts are mentioned in the documentation, beginners might not fully understand when and why they should always be used.

Problem:
Timeouts are critical for real-world applications to avoid hanging HTTP requests.
Although timeouts are mentioned in the documentation, beginners may not fully understand
why they should always be used and how they affect application reliability.

This can lead to applications without timeouts, which may block indefinitely
when a server is slow or unresponsive.

Proposed Improvement:
Add a small "Timeout Best Practices" section to the documentation that:

  • explains why timeouts are important
  • shows a simple example using a timeout value
  • clarifies that timeouts apply to connect and read operations

Why this is useful:
Clear guidance on timeout usage helps users write safer and more reliable applications.
It reduces common beginner mistakes and improves overall developer experience.

Acceptance Criteria

  • Documentation contains a short best-practices section for timeouts
  • Includes a simple code example
  • Explanation is concise and beginner-friendly

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions