Use timeout with int instead of num_sec

[LadislavVasina1]

This PR is CP of for legacy-selenium-support branch that is used in https://github.com/SatelliteQE/airgun.

From the parent PR:
The timeout kwarg should be an integer, float, or timedelta instance

Also, num_sec will be deprecated.

Summary by Sourcery

Standardize timeout handling on integer-based timeout parameters instead of string-based or num_sec arguments across browser safety checks, element lookup, and wait strategies.

Enhancements:

• Update widget and browser APIs to use numeric timeout defaults instead of string durations.
• Switch internal wait calls from the deprecated num_sec parameter to the timeout parameter for consistency with the underlying wait utility.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Standardizes timeout handling across widgetastic by switching string-based timeouts and the deprecated num_sec argument to integer-based timeout parameters, aligning with the updated wait_for API and deprecation plan.

File-Level Changes

Change	Details	Files
Standardize browser-level timeout usage and propagate new timeout parameter into wait_for calls.	Change Browser.ensure_page_safe signature to accept a numeric timeout with default 10 instead of a string formatted timeout Update wait_for invocation to use the timeout keyword argument instead of the deprecated num_sec parameter Ensure that the timeout value is passed through unchanged from widget calls into wait_for	src/widgetastic/browser.py
Align WaitFillViewStrategy default wait_widget timeout with numeric-based configuration.	Update WaitFillViewStrategy.init to use an integer default for wait_widget instead of a string-formatted timeout Preserve existing behavior while preparing for deprecation of string-based duration handling	src/widgetastic/utils.py
Standardize widget wait_displayed timeout to use numeric values instead of string durations.	Change Widget.wait_displayed timeout default from a string duration to an integer number of seconds Keep delay behavior the same while aligning timeout API with the new wait_for expectations	src/widgetastic/widget/base.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• Consider updating the method signatures with explicit type hints for the timeout/wait_widget parameters (e.g., Union[int, float, timedelta]) to reflect the new accepted types and improve static checking.
• If any existing callers may still pass values like '10s', you might want to add a small compatibility layer (e.g., accepting both strings and numeric and normalizing) to avoid silent breakage when moving from "10s" to numeric defaults.
• Now that timeout is numeric rather than a duration string, it may be helpful to ensure all internal uses treat it consistently as seconds and avoid any remaining assumptions about string-based time parsing in the called utilities (like wait_for).

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider updating the method signatures with explicit type hints for the `timeout`/`wait_widget` parameters (e.g., `Union[int, float, timedelta]`) to reflect the new accepted types and improve static checking.
- If any existing callers may still pass values like `'10s'`, you might want to add a small compatibility layer (e.g., accepting both strings and numeric and normalizing) to avoid silent breakage when moving from `"10s"` to numeric defaults.
- Now that `timeout` is numeric rather than a duration string, it may be helpful to ensure all internal uses treat it consistently as seconds and avoid any remaining assumptions about string-based time parsing in the called utilities (like `wait_for`).

## Individual Comments

### Comment 1
<location path="src/widgetastic/browser.py" line_range="102" />
<code_context>
         return create_widget_logger(type(self).__name__, self.browser.logger)

-    def ensure_page_safe(self, timeout: str = "10s") -> None:
+    def ensure_page_safe(self, timeout=10) -> None:
         # THIS ONE SHOULD ALWAYS USE JAVASCRIPT ONLY, NO OTHER SELENIUM INTERACTION

</code_context>
<issue_to_address>
**suggestion:** Consider keeping a concrete type annotation for `timeout` now that it is numeric seconds.

Since the default is now a bare `10`, this parameter is effectively “seconds as a number”. A concrete annotation like `timeout: int | float = 10` would improve static checking and make it clear that string formats like "10s" are no longer accepted, which helps callers migrating to the new convention.

```suggestion
    def ensure_page_safe(self, timeout: int | float = 10) -> None:
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion: Consider keeping a concrete type annotation for timeout now that it is numeric seconds.

Since the default is now a bare 10, this parameter is effectively “seconds as a number”. A concrete annotation like timeout: int | float = 10 would improve static checking and make it clear that string formats like "10s" are no longer accepted, which helps callers migrating to the new convention.

Suggested change

	def ensure_page_safe(self, timeout=10) -> None:
	def ensure_page_safe(self, timeout: int | float = 10) -> None:

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.35%. Comparing base (d0d0f36) to head (e3b6a13).

Additional details and impacted files

@@                     Coverage Diff                     @@
##           legacy-selenium-support     #309      +/-   ##
===========================================================
- Coverage                    86.54%   86.35%   -0.20%     
===========================================================
  Files                           18       18              
  Lines                         2572     2572              
===========================================================
- Hits                          2226     2221       -5     
- Misses                         346      351       +5     

Flag	Coverage Δ
unittests	86.35% <100.00%> (-0.20%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.