Goal
Replace indistinct ValueError mapping for raw client setup failures with a stable public configuration error type.
Context
create_raw_client currently catches _foghttp.FogHttpError and raises ValueError(str(exc)). That keeps construction failures user-visible, but it erases whether the failure came from TLS, proxy endpoint parsing, numeric config or runtime setup. Tests then match text strings, which is fragile for a stability milestone.
Scope
- Add a public
ConfigurationError in the FogHTTP error hierarchy.
- Map raw client setup/configuration failures to
ConfigurationError.
- Consider subclassing
ValueError if needed to preserve compatibility with existing callers.
- Update tests to assert the error type and stable diagnostic fields/substrings rather than brittle full text.
- Document the setup/configuration error class where public errors are listed.
Out Of Scope
- Retyping every runtime request error.
- Changing successful client construction behavior.
Acceptance Criteria
- Client setup/config failures use
ConfigurationError.
- Compatibility with existing
ValueError handling is preserved or explicitly documented as a 0.4.0-breaking decision.
- Tests do not depend on fragile full error-message text.
- Public docs list the new error type.
Test And Check Strategy
uv run pytest tests/client_proxy tests/client_tls tests/client_options tests/test_raw_client_errors.py
uv run mypy foghttp
uv run pre-commit run --all-files
Documentation Impact
- Update error docs and 0.4.0 release notes.
Risks
- Risk: changing exception type surprises early adopters.
Mitigation: consider subclassing ValueError and document the migration path.
Goal
Replace indistinct
ValueErrormapping for raw client setup failures with a stable public configuration error type.Context
create_raw_clientcurrently catches_foghttp.FogHttpErrorand raisesValueError(str(exc)). That keeps construction failures user-visible, but it erases whether the failure came from TLS, proxy endpoint parsing, numeric config or runtime setup. Tests then match text strings, which is fragile for a stability milestone.Scope
ConfigurationErrorin the FogHTTP error hierarchy.ConfigurationError.ValueErrorif needed to preserve compatibility with existing callers.Out Of Scope
Acceptance Criteria
ConfigurationError.ValueErrorhandling is preserved or explicitly documented as a 0.4.0-breaking decision.Test And Check Strategy
uv run pytest tests/client_proxy tests/client_tls tests/client_options tests/test_raw_client_errors.pyuv run mypy foghttpuv run pre-commit run --all-filesDocumentation Impact
Risks
Mitigation: consider subclassing
ValueErrorand document the migration path.