Skip to content

feat(python-wrapper): use explicit parameters in Client.__init__#10438

Open
caoergou wants to merge 2 commits into
treeverse:masterfrom
caoergou:fix/8720-client-explicit-params
Open

feat(python-wrapper): use explicit parameters in Client.__init__#10438
caoergou wants to merge 2 commits into
treeverse:masterfrom
caoergou:fix/8720-client-explicit-params

Conversation

@caoergou

@caoergou caoergou commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

Change Description

Background

Builds on #10284 (mypy CI integration) to improve the Python wrapper's type safety and usability.
`Client.init` previously accepted only `**kwargs`, giving IDEs no help with auto-completion or
type checking, and leaving users to guess what parameters are valid.

Changes

`Client.init` — explicit parameters

The six most common configuration parameters are now named keyword-only arguments:

```python

Before

client = Client(host="...", username="...", password="...") # no IDE hints

After — IDE shows completions, mypy checks types

client = Client(host="...", username="...", password="...")
```

Parameters added: `host`, `username`, `password`, `access_token`, `verify_ssl`, `proxy`.
`**kwargs` is retained so less common `lakefs_sdk.Configuration` options (e.g. `ssl_ca_cert`) keep working.

Note: only non-`None` values are forwarded to `ClientConfig` to preserve its auto-detection behaviour
(env vars / `~/.lakectl.yaml`) when no credentials are supplied.

Return type annotations

Added return types to previously unannotated members:

Member Return type
`config` `ClientConfig`
`sdk_client` `LakeFSClient`
`storage_config` `ServerStorageConfiguration`
`reset_time` `Optional[datetime.datetime]`
`storage_config_by_id` (Client + ServerConfiguration) `ServerStorageConfiguration`
`_refresh_token_if_necessary` `None`

Class attribute annotations

`_client` and `_conf` are now declared as non-Optional at the class level (`LakeFSClient` / `ClientConfig`),
since `init` always sets them unconditionally. `_server_conf` remains `Optional` (lazy-loaded).

IAM token refresh — None guards

Annotating `_refresh_token_if_necessary` caused mypy to check its body, exposing latent issues:

  • `iam_provider` (type `Optional[IAMProvider]`) was accessed without a None check
  • `iam_provider.aws_iam` (type `Optional[AWSIAMProviderConfig]`) was accessed without a None check
  • `urlparse(host).hostname` returns `Optional[str]`, passed to a `str` parameter

These are now guarded with explicit `if` checks (not `assert`, which is disabled under `python -O`).
In `init`, an invalid hostname raises `ValueError` with a clear message. In the token-refresh path,
an invalid hostname silently skips the refresh to avoid surfacing a hard error during an in-flight call.

Testing Details

  • `bash lint.sh` — mypy clean (0 errors, 20 files); pylint 10.0/10 on changed file
  • `pytest tests/utests/` — 53 passed

Closes #8720

Replace `**kwargs` with named parameters in `Client.__init__` to improve
IDE auto-completion, type checking, and readability. The six most common
configuration parameters (host, username, password, access_token,
verify_ssl, proxy) are now explicit; remaining kwargs are still forwarded
to the underlying SDK for less common options.

Also adds return type annotations to `config`, `sdk_client`,
`storage_config`, `reset_time`, `storage_config_by_id`, and
`_refresh_token_if_necessary`, and adds None-guards in the IAM token
refresh path that mypy now checks.

Closes treeverse#8720
…M block

Using assert in library code is fragile: it is silently disabled when Python
runs with -O, and AssertionError is not the right exception type to expose to
callers. Replace the three assert guards added in the previous commit:

- iam_provider None-check: moved into the if-condition alongside the type check
- iam_provider.aws_iam None-check: same
- invalid hostname: raise ValueError with a clear message in __init__;
  silently return (skip refresh) in _refresh_token_if_necessary since a
  token expiry mid-flight should not surface as a hard error
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Enhance Type Hints in lakeFS Python SDK to Improve Usability

1 participant