[CLI] Make top-level Flow360 import lazy

[maciej-flexcompute]

Summary

This PR keeps the PR1 CLI foundation lightweight by making import flow360 lazy:

• moves the heavy public SDK imports from flow360/__init__.py into flow360/_api.py
• exposes the same public API through __getattr__ without importing heavy modules during root package import
• preserves the legacy lazy flow360.version_check attribute path
• moves API key configuration storage into flow360.user_config so flow360.configure no longer imports the Click CLI app
• adds focused lazy-import regression tests

This intentionally does not include the later resource CLI commands, delete commands, logs, or mutation workflow work.

Validation

• poetry run pytest tests/test_lazy_imports.py tests/test_cli.py tests/test_cli_login.py -q -> 20 passed in 4.16s
• poetry run pytest tests/test_version_check.py -q -> 3 passed in 0.03s
• direct timing through poetry run: import flow360 -> 0.008551s, with flow360._api=False, pandas=False
• direct timing through poetry run: import flow360.cli.app -> 0.744254s, with _api/project/folder/flow360_requests not imported

CLI Performance Comparison

Methodology:

• Baseline checkout: Flow360-pr1
• Lazy-loading checkout: Flow360-pr1.5
• Invocation: direct virtualenv flow360 executable, not poetry run
• Each command: 8 runs, first run discarded, median reported
• Environment: FLOW360_SUPPRESS_BETA_WARNING=1
• Scope: every root CLI command and every project / folder subcommand via --help, to isolate startup/import and command-dispatch latency from network/auth latency

Command	PR1 median	PR1.5 median	Speedup
flow360 --help	2934 ms	201 ms	14.6x
flow360 configure --help	2897 ms	706 ms	4.1x
flow360 login --help	2884 ms	632 ms	4.6x
flow360 logout --help	3139 ms	653 ms	4.8x
flow360 show_projects --help	3647 ms	656 ms	5.6x
flow360 version --help	2915 ms	660 ms	4.4x
flow360 project --help	2892 ms	639 ms	4.5x
flow360 project info --help	2859 ms	681 ms	4.2x
flow360 project items --help	2881 ms	639 ms	4.5x
flow360 project list --help	2903 ms	632 ms	4.6x
flow360 project path --help	2974 ms	653 ms	4.6x
flow360 project tree --help	2976 ms	639 ms	4.7x
flow360 folder --help	2902 ms	640 ms	4.5x
flow360 folder get --help	2892 ms	716 ms	4.0x
flow360 folder tree --help	3026 ms	877 ms	3.5x

Result: PR1.5 is consistently faster across the full CLI help surface. Root flow360 --help drops from ~2.9s to ~0.2s, and subcommands generally drop from ~2.9-3.6s to ~0.63-0.88s.

---

Note

Medium Risk
Medium risk because it rewires flow360 package exports and lazy-loading behavior, which can cause subtle import-time/regression issues if __all__ or attribute resolution diverges from prior behavior.

Overview
flow360’s root package is refactored into a lazy facade: the previous eager mass-imports are moved into a new flow360/_public_namespace.py, and flow360/__init__.py now exposes the same API via __getattr__ that loads symbols on demand.

__all__ is now derived by parsing _public_namespace.py’s __all__ via ast, __dir__ is updated accordingly, and a new __init__.pyi stub statically re-exports the public names for type checkers. configure is reimplemented in _public_namespace to lazily import the CLI configure caller, and expanded tests assert that importing flow360/CLI help paths do not eagerly import heavy dependencies or CLI command modules and that stub exports match _public_namespace.__all__.

^{Reviewed by Cursor Bugbot for commit b2048d7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Coverage report (flow360)

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
flow360
__init__.py					28, 31, 65-66, 74
_public_namespace.py					223-225
Project Total

This report was generated by python-coverage-comment-action

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 95e2ba6. Configure here.}