feat: actionable guidance for removed v2 interfaces

[jam-jee]

Issue #, if available: N/A

Description of changes:

In v3 the v2 top-level modules were removed, so importing one fails with a bare, dead-end error:

>>> import sagemaker.estimator
ModuleNotFoundError: No module named 'sagemaker.estimator'

This PR turns that into an actionable migration experience. (Usage telemetry for these events is a follow-up, tracked in a separate stacked PR so it can be reviewed independently.)

• raise_removed_in_v3() in sagemaker.core.deprecations — emits a DeprecationWarning, then raises ModuleNotFoundError naming the exact v3 replacement, the copy-pasteable import, and a direct API-docs link + the migration guide.
• 12 curated tombstone modules under sagemaker/ for the high-traffic removed interfaces (estimator, model, predictor, base_predictor, predictor_async, transformer, tuner, processing, pipeline, multidatamodel, automl, algorithm). Each points at a verified-importable v3 target + its docs page. They ship with sagemaker-core (verified in the built wheel).
• Fallback meta-path finder (_RemovedV2ModuleFinder) as a last resort for the remaining removed modules. Registered from sagemaker-core's namespace sagemaker/__init__.py so it is active on any import sagemaker.* (including when a removed module is the very first import). It is appended to sys.meta_path so it never shadows real v3 packages or the tombstones. Two guards keep messages truthful:
  • _KNOWN_V3_TOPLEVEL — never intercepts real v3 packages (core/train/serve/mlops/lineage/ai_registry), even when a package simply isn't installed.
  • _REMOVED_V2_MODULES — only emits guidance for names that actually existed in v2 (derived from the master-v2 top-level surface). Typos / hallucinated imports fall through to a plain ModuleNotFoundError.

Resulting UX

1. Curated (tombstoned) removed interface — precise replacement + import + docs:

>>> import sagemaker.estimator
ModuleNotFoundError: `sagemaker.estimator` was removed in the SageMaker Python SDK v3.
Use `ModelTrainer`. (from sagemaker.train import ModelTrainer)
Docs: https://sagemaker.readthedocs.io/en/stable/api/generated/sagemaker.train.model_trainer.html
See https://github.com/aws/sagemaker-python-sdk/blob/master/migration.md for the migration guide.

2. Non-tombstoned removed v2 module — generic guidance via the fallback finder:

>>> import sagemaker.clarify
ModuleNotFoundError: `sagemaker.clarify` was removed in the SageMaker Python SDK v3.
It may have moved to a new location.
See https://github.com/aws/sagemaker-python-sdk/blob/master/migration.md for the migration guide.

3. Unknown name (typo / never existed) — plain error, no misleading guidance:

>>> import sagemaker.foobar
ModuleNotFoundError: No module named 'sagemaker.foobar'

Testing done:

• tests/unit/test_removed_v2_modules.py — 44 tests, all pass. Covers: tombstone messages (import + docs URL present), the fallback finder (registration on bare import sagemaker, append-ordering, non-shadowing of real packages, guidance only for known removed names, pass-through for unknown names), and a fresh-interpreter regression that a removed module gets guidance even as the first sagemaker import.
• Verified real v3 imports (sagemaker.train, sagemaker.serve, sagemaker.core) are unaffected.
• All v3 replacement imports and docs URLs verified against the installed packages and readthedocs.
• Built a sagemaker-core wheel and confirmed all 12 tombstones are packaged.
• black (line-length 100) and flake8 (repo tox.ini) clean.

Merge Checklist

General

• I have read the CONTRIBUTING doc
• I certify that the changes I am introducing will be backward compatible, and I have discussed concerns about this, if any, with the Python SDK team
  • Note: additive only (guidance for already-removed modules). No existing public API changes. Flagging for awareness: the fallback finder is registered at import sagemaker time via the namespace package init (guarded, best-effort).
• I used the commit message format described in CONTRIBUTING
• I have passed the region in to all S3 and STS clients that I've initialized as part of this change. (N/A — no clients initialized in this PR)
• I have updated any necessary documentation
  • Note: migration.md lists two paths that do not resolve in shipped v3 (sagemaker.mlops.pipeline, sagemaker.mlops.processing.DataProcessor); this PR anchors to the verified paths (sagemaker.mlops.workflow.pipeline, sagemaker.core.resources.ProcessingJob). The guide may need a follow-up fix.

Tests

• I have added tests that prove my fix is effective or that my feature works
• I have added unit tests as appropriate to ensure backward compatibility of the changes
• I have checked that my tests are not configured for a specific region or account
• I have used unique_name_from_base to create resource names in integ tests (if appropriate) (N/A — unit tests only)
• If adding any dependency in requirements.txt files, I have spell checked and ensured they exist in PyPi (N/A — no new dependencies)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[mohanasudhan]

Can we point to samples of ModelTrainer instead of generic message - https://github.com/aws/sagemaker-python-sdk/blob/master/migration.md ?

[jam-jee]

Can we point to samples of ModelTrainer instead of generic message - https://github.com/aws/sagemaker-python-sdk/blob/master/migration.md ?

Updated message thrown. Resulting UX detailed in PR description.