Even more consistent timeouts for all long-running APIs

[achimnol]

What do these changes do?

This PR extends the timeout configuration improvements from #990 by:

1. Making Docker API parameters explicit - Replaced **kwargs with explicit parameters in container methods:

   • DockerContainer.stop() - now accepts t (server-side graceful shutdown timeout), signal (signal to send), and timeout (client-side HTTP request timeout)
   • DockerContainer.restart() - now accepts t (server-side graceful shutdown timeout) and timeout (client-side HTTP request timeout)
   • DockerContainer.kill() - now accepts signal (signal to send) and timeout (client-side HTTP request timeout)
   • DockerContainer.delete() - now accepts force, v (volumes), link, and timeout (client-side HTTP request timeout)
   • Exec.start(), DockerEvents.run() - now accepts timeout for client-side HTTP request timeout with the default of infinite timeout like other methods updated in #983 and #990

2. Documentation - Added detailed documentation explaining the distinction between Docker API parameters (like t for graceful shutdown) and HTTP request timeouts.

3. New tests - Added three test cases that verify:

   • Containers are successfully stopped with server-side graceful timeout
   • Containers are eventually stopped even when HTTP request times out (demonstrating independence of server-side and client-side timeouts)
   • Containers are successfully deleted with force=True parameter

Are there changes in behavior for the user?

Warning

• Methods that previously accepted **kwargs now have explicit parameters, which may break code that passes unexpected keyword arguments
• The t parameter in stop() and restart() is now explicit instead of being part of **kwargs
• BREAKING: All users who have used timeout parameter of DockerContainer.restart() method should update their codes to pass t instead.

Improvements:

• Clear separation between Docker API parameters and HTTP request timeouts
• Better IDE autocomplete and type checking support
• More discoverable API with explicit parameter names

Related issue number

Continues work from #990

Checklist

• I think the code is well written
• Unit tests for the changes exist
• Documentation reflects the changes
• Add a new news fragment into the CHANGES folder

[codecov]

Codecov Report

❌ Patch coverage is 65.78947% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.03%. Comparing base (972d3e1) to head (3d59afc).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
aiodocker/containers.py	60.00%	8 Missing and 4 partials ⚠️
aiodocker/events.py	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #991      +/-   ##
==========================================
- Coverage   73.27%   73.03%   -0.24%     
==========================================
  Files          25       25              
  Lines        1815     1836      +21     
  Branches      244      250       +6     
==========================================
+ Hits         1330     1341      +11     
- Misses        405      410       +5     
- Partials       80       85       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.