Repository navigation
Commit 1e1cbcf
authored
feat: actionable guidance for removed v2 interfaces (#6004)
* feat: actionable guidance for removed v2 interfaces
In v3 the v2 top-level modules (sagemaker.estimator, sagemaker.model, ...)
were removed, so importing them fails with a bare
"ModuleNotFoundError: No module named 'sagemaker.estimator'" that gives the
caller no path forward. This adds an actionable migration experience.
- raise_removed_in_v3() helper in sagemaker.core.deprecations: emits a
DeprecationWarning and raises a ModuleNotFoundError naming the v3
replacement (and the exact import where the migration guide publishes
one), plus the migration-guide link.
- 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). These ship with sagemaker-core.
- A fallback meta-path finder (_RemovedV2ModuleFinder) registered from
sagemaker.core.__init__ as a last resort: any other removed
sagemaker.<name> gets a generic "not available in v3, see migration
guide" message instead of a bare error. Appended to sys.meta_path so it
never shadows real v3 packages or the tombstones, with a
_KNOWN_V3_TOPLEVEL guard protecting real packages
(core/train/serve/mlops/lineage/ai_registry).
Adds tests/unit/test_removed_v2_modules.py (36 tests) covering tombstone
messages and the fallback finder (registration, ordering, non-shadowing of
real packages, pass-through of non-sagemaker and nested names).
* refactor: log removed-module guidance at debug, not warning
The raised ModuleNotFoundError is the loud, authoritative signal (it stops
execution and carries the full message with the v3 replacement + migration
link). Logging the same message at WARNING duplicated it noisily on a path
that always raises. Downgrade the logger call to debug in both
raise_removed_in_v3 (tombstones) and the fallback finder (catch-all),
leaving a breadcrumb for log-captured environments without the noise. The
DeprecationWarning and the raise are unchanged.
* docs: simplify fallback message to 'It may have been removed'
* test: assert finder pass-through via find_spec, not real import
test_finder_does_not_shadow_real_v3_packages imported sagemaker.train /
sagemaker.serve to prove the fallback finder does not shadow them. That
assumed those packages are installed -- but the sagemaker-core unit-test
CI job installs sagemaker-core only, so the import raised
ModuleNotFoundError and the test failed.
Assert the actual contract instead: the finder's find_spec() returns None
(pass-through) for real v3 top-level packages, which needs no import and
holds in a core-only environment. Also covers mlops and lineage.
* feat: point removed-interface errors at verified v3 code + docs
Address PR feedback: name the actual v3 replacement (identifiable in the
repo) and link its API docs, instead of vague package references.
- Add a v3_docs argument to raise_removed_in_v3 so each message carries a
direct readthedocs API link alongside the copy-pasteable import.
- Update all 12 tombstones to verified-importable v3 targets + docs URLs:
estimator/algorithm -> sagemaker.train.ModelTrainer
model/multidatamodel -> sagemaker.serve.ModelBuilder
predictor/base_predictor -> sagemaker.core.resources.Endpoint
predictor_async -> sagemaker.serve.ModelBuilder
transformer -> sagemaker.core.resources.TransformJob
tuner -> sagemaker.core.resources.HyperParameterTuningJob
processing -> sagemaker.core.resources.ProcessingJob
pipeline -> sagemaker.mlops.workflow.pipeline.Pipeline
automl -> sagemaker.core.resources.AutoMLJob
Corrects two paths that did not resolve in the shipped v3 code (the
migration guide's sagemaker.mlops.pipeline and sagemaker.mlops.processing
.DataProcessor): Pipeline is at sagemaker.mlops.workflow.pipeline, and
processing maps to the core ProcessingJob resource. All imports and docs
URLs were verified against the installed packages and readthedocs.
Tests assert the import statement and docs URL are present in every
message; updated expected symbols for tuner and processing.
* fix: fallback finder only guides for known removed v2 modules
Previously the fallback finder emitted "was removed in v3" guidance for
ANY top-level sagemaker.<name> that was not a real v3 package -- including
typos and hallucinated imports like `sagemaker.foobar`, which never
existed and so should not claim to have been removed.
Gate the finder on _REMOVED_V2_MODULES, the set of top-level modules that
actually existed in v2 (derived from the master-v2 branch, minus names
still present in v3). Unknown names now fall through to a plain
ModuleNotFoundError with no deprecation warning and no migration link.
Because the name is now known to be a real v2 module, the message states
"was removed" (was "may have been removed").
Adds tests: known removed names -> guidance; unknown names -> plain error
with no warning/link; finder find_spec pass-through for unknown names.
* fix: register fallback finder on any sagemaker import, not just core
The fallback finder was registered only from sagemaker/core/__init__.py, so
a removed module imported as the very first sagemaker statement (e.g.
`import sagemaker.estimator` with nothing else loaded) missed the guidance
and got a bare ModuleNotFoundError -- the finder had not been installed yet.
Register it from sagemaker-core's namespace sagemaker/__init__.py, which
runs on any `import sagemaker.*` (these are pkgutil-style namespace
packages whose __init__ executes). Fully guarded so it can never interfere
with importing the package. Tombstone modules were unaffected (real files),
and normal usage already pulled in core transitively; this closes the
first-import edge case.
Adds a fresh-interpreter regression test asserting a removed module gets
guidance even as the first sagemaker import.
* refactor: consolidate removed-module guidance into the finder
Address review: the 12 per-module "tombstone" files were not strictly
necessary -- the meta-path finder receives the full module name, so it can
produce the same precise guidance from a lookup table.
- Add _V3_REPLACEMENTS: curated (replacement, import, docs) for the 12
high-traffic removed modules. find_spec now emits the precise message for
these, a generic "was removed" message for other _REMOVED_V2_MODULES, and
a plain ModuleNotFoundError for unknown names (typos).
- Delete the 12 tombstone modules under src/sagemaker/. Behavior is
unchanged for users (verified: same precise messages), with one mechanism
instead of files + finder.
- Add a debug log when the finder registers (review comment).
- Add name-set invariants (review comment "what prevents a collision?"):
_REMOVED_V2_MODULES is disjoint from real v3 top-level packages, all
curated keys are in the removed set, and a real module under a removed
name still wins over the appended finder (never shadowed).
47 unit tests pass; black + flake8 clean.
* feat: expand precise v3 guidance to 34 modules + validate targets in CI
Now that guidance is data-driven (no per-module files), extend the curated
_V3_REPLACEMENTS map from 12 to 34 removed v2 modules -- every framework
estimator, inference/serverless/jumpstart interface, core resource
(clarify/wrangler/spark/model_monitor/feature_store/experiments/model_card),
relocated utility (image_uris/s3/serializers/deserializers), workflow, and
inputs/session. Each replacement import and docs URL was verified against
installed v3 and readthedocs. The remaining removed modules (internal utils,
hard-removed frameworks like mxnet/chainer/rl) keep the generic message --
they have no user-facing v3 replacement to point at.
Maintenance guards (recommendation from review):
- test_curated_v3_imports_resolve: imports every replacement target (via
pytest.importorskip so it runs in the all-extras lane and skips cleanly in
the core-only job), so a future rename/move fails CI instead of shipping a
dead import string.
- test_curated_docs_url_matches_import_module_root: the docs URL is a
derivation of the import's module path, asserted to share the same
top-level package so the two cannot drift apart.
82 unit tests pass; black + flake8 clean.1 parent 17b2679 commit 1e1cbcf
4 files changed
Lines changed: 665 additions & 1 deletion
File tree
- sagemaker-core
- src/sagemaker
- core
- tests/unit
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | | - | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
| 2 | + | |
2 | 3 | | |
| 4 | + | |
3 | 5 | | |
4 | 6 | | |
5 | 7 | | |
6 | 8 | | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
7 | 16 | | |
8 | 17 | | |
9 | 18 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
13 | 13 | | |
14 | 14 | | |
15 | 15 | | |
| 16 | + | |
16 | 17 | | |
| 18 | + | |
17 | 19 | | |
18 | 20 | | |
19 | 21 | | |
20 | 22 | | |
21 | 23 | | |
22 | 24 | | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
| 209 | + | |
| 210 | + | |
| 211 | + | |
| 212 | + | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
| 232 | + | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
| 236 | + | |
| 237 | + | |
| 238 | + | |
| 239 | + | |
| 240 | + | |
| 241 | + | |
| 242 | + | |
| 243 | + | |
| 244 | + | |
| 245 | + | |
| 246 | + | |
| 247 | + | |
| 248 | + | |
| 249 | + | |
| 250 | + | |
| 251 | + | |
| 252 | + | |
| 253 | + | |
| 254 | + | |
| 255 | + | |
| 256 | + | |
| 257 | + | |
| 258 | + | |
| 259 | + | |
| 260 | + | |
| 261 | + | |
| 262 | + | |
| 263 | + | |
| 264 | + | |
| 265 | + | |
| 266 | + | |
| 267 | + | |
| 268 | + | |
| 269 | + | |
| 270 | + | |
| 271 | + | |
| 272 | + | |
| 273 | + | |
| 274 | + | |
| 275 | + | |
| 276 | + | |
| 277 | + | |
| 278 | + | |
| 279 | + | |
| 280 | + | |
| 281 | + | |
| 282 | + | |
| 283 | + | |
| 284 | + | |
| 285 | + | |
| 286 | + | |
| 287 | + | |
| 288 | + | |
| 289 | + | |
| 290 | + | |
| 291 | + | |
| 292 | + | |
| 293 | + | |
| 294 | + | |
| 295 | + | |
| 296 | + | |
| 297 | + | |
| 298 | + | |
| 299 | + | |
| 300 | + | |
| 301 | + | |
| 302 | + | |
| 303 | + | |
| 304 | + | |
| 305 | + | |
| 306 | + | |
| 307 | + | |
| 308 | + | |
| 309 | + | |
| 310 | + | |
| 311 | + | |
| 312 | + | |
| 313 | + | |
| 314 | + | |
| 315 | + | |
| 316 | + | |
| 317 | + | |
| 318 | + | |
| 319 | + | |
| 320 | + | |
| 321 | + | |
| 322 | + | |
| 323 | + | |
| 324 | + | |
| 325 | + | |
| 326 | + | |
| 327 | + | |
| 328 | + | |
| 329 | + | |
| 330 | + | |
| 331 | + | |
| 332 | + | |
| 333 | + | |
| 334 | + | |
| 335 | + | |
| 336 | + | |
| 337 | + | |
| 338 | + | |
| 339 | + | |
| 340 | + | |
| 341 | + | |
| 342 | + | |
| 343 | + | |
| 344 | + | |
| 345 | + | |
| 346 | + | |
| 347 | + | |
| 348 | + | |
| 349 | + | |
23 | 350 | | |
24 | 351 | | |
25 | 352 | | |
| |||
0 commit comments