refactor: Consolidate public interface for v3

[vdusek]

Description

Consolidates the public interface for the v3 release:

• Root apify_client namespace now only exposes ApifyClient, ApifyClientAsync, and __version__. This is a go-to for everyone.
• HTTP client abstractions moved to http_clients submodule (HttpClient, HttpClientAsync, HttpResponse, ImpitHttpClient, ImpitHttpClientAsync). Only for people who want to replace the default HTTP client.
• New public types.py module with Timeout, WebhooksList, and JsonSerializable type aliases (can be used, e.g., for a custom HTTP client).
• Add missing __all__ to errors.py.
• Update v3 upgrade guide and doc snippets to reflect new import paths.
• Not breaking, because HTTP clients were not part of v2.5.

I would prefer to keep _models and _typeddicts private. They should not be considered safe to import, since exposing them publicly would potentially restrict future API changes. For typed dicts, users do not need to import them to pass inputs to resource client methods. Resource clients, which are also private and users should be able to get to them only via ApifyClient (and its async version), may return Pydantic models, but those models should not be constructed directly in user code. There may be niche cases where users want to import models or typed dicts for explicit typing or casts, but I would rather keep those available only on the user's own responsibility - we cannot guarantee that the types will not change. This is also a status quo in the current v2.5.

This is my stand, let me know yours @janbuchar.

Issue

Closes: #744

[codecov]

Codecov Report

❌ Patch coverage is 53.84615% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.74%. Comparing base (d1bd5a3) to head (210c840).
⚠️ Report is 10 commits behind head on master.

Files with missing lines	Patch %	Lines
src/apify_client/types.py	0.00%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #794      +/-   ##
==========================================
- Coverage   97.73%   95.74%   -2.00%     
==========================================
  Files          48       49       +1     
  Lines        4860     4863       +3     
==========================================
- Hits         4750     4656      -94     
- Misses        110      207      +97     

Flag	Coverage Δ
integration	91.81% <53.84%> (-1.85%)	⬇️
unit	84.20% <53.84%> (-1.99%)	⬇️

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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[janbuchar]

I'm not sure if apify_client.types is actually necessary to develop a new Client, but otherwise I completely agree with the changes, thanks, well done!

[vdusek]

I'm not sure if apify_client.types is actually necessary to develop a new Client, but otherwise I completely agree with the changes, thanks, well done!

Well, probably only Timeout is needed, so wondering... Maybe we shall keep _types.py private and add a new module types.py exporting public "types"?

[janbuchar]

I'm not sure if apify_client.types is actually necessary to develop a new Client, but otherwise I completely agree with the changes, thanks, well done!

Well, probably only Timeout is needed, so wondering... Maybe we shall keep _types.py private and add a new module types.py exporting public "types"?

Yeah, that sounds good to me. Maybe we should think about the naming some more though