Add structured deprecation info and warnings - #3326
Merged
deruyter92 merged 3 commits intoMay 12, 2026
Merged
Conversation
Introduce a DLCDeprecationWarning and a DeprecationInfo pydantic model to standardize deprecation metadata (kind, target, replacement, since, removed_in, renamed params) with parsing and validation of versions. Revamp deprecated and renamed_parameter decorators to build messages from DeprecationInfo, emit DLCDeprecationWarning, attach metadata to wrapped callables (__deprecated_info__, __deprecated_params__), use ParamSpec/TypeVar typing for wrappers, and enforce error when both old and new kwargs are passed. Switch to packaging.version for version parsing.
Replace generic DeprecationWarning checks with DLCDeprecationWarning and import packaging.version.Version. Add tests verifying deprecated decorators attach metadata (including since/removed_in parsed as Version), validate invalid version inputs, and ensure removed_in > since. Also add tests for renamed_parameter behavior (conflicting old+new raises, metadata attachment, and invalid since handling) and small docstring/name preservation assertions.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR formalizes DeepLabCut’s deprecation system by introducing structured deprecation metadata and a project-specific warning class, then refactors the deprecated / renamed_parameter decorators to build validated messages and attach machine-readable metadata to wrapped callables.
Changes:
- Add
DLCDeprecationWarningand aDeprecationInfo(pydantic) model with version parsing/validation viapackaging.version.Version. - Refactor
deprecatedandrenamed_parameterto emitDLCDeprecationWarning, useParamSpec/TypeVartyping, attach__deprecated_info__/__deprecated_params__, and error if both old+new kwargs are provided. - Extend tests to assert the new warning category, metadata attachment, and version validation behavior.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
deeplabcut/utils/deprecation.py |
Introduces structured deprecation metadata + warning type and refactors decorators to use them. |
tests/utils/test_deprecation.py |
Updates/extends tests to cover the new warning type, metadata, and version validation behaviors. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
C-Achard
marked this pull request as ready for review
May 12, 2026 09:44
deruyter92
approved these changes
May 12, 2026
deruyter92
left a comment
deruyter92
left a comment
Collaborator
There was a problem hiding this comment.
Great idea to structure this into validated classes.
Collaborator
Author
|
@deruyter92 Would you rather merge this in #3303 or merge #3303 then this into main ? |
8 tasks
deruyter92
merged commit May 12, 2026
77a05dc
into
jaap/update_list_videos_in_folder
4 checks passed
MMathisLab
added a commit
that referenced
this pull request
May 15, 2026
* Update `list_video_files_in_folder` only filter explicitly provided files if filter `video_type` is set. - Accept files without extension - Default folder searching is kept as is (using valid video extensions) * add test for list_videos_in_folder * Add deprecation utils: decorator for deprecated functions * move `list_videos_in_folder` to `collect_video_paths` in auxfun_videos.py * export `deeplabcut.collect_video_paths(..)` from auxfun_videos.py * update `collect_video_paths`: add exclude patterns * deprecate auxfun `get_list_of_videos` in favor of `collect_video_paths` * add pytest deprecation marker `test_get_list_of_videos` * Mark `get_video_list` as deprecated (keep for now for backward compatibility) * fix test_collect_video_paths: rename keyword -> extensions * Adjust `extensions` parameter: flexibly coerce str / list / tuple -> set of extensions. * `collect_video_paths`: sort videos if shuffle=False * update docstring non-recursive directory scanning. * update collect_video_paths: DEFAULT_EXCLUDE_PATTERNS * update _coerce_extensions: only "" and None normalize to None * fix instance check in _coerce_video_extensions * fix pytest: assert alphabetic ordering if shuffle=False * fix empty string case in _coerce_extensions * Add structured deprecation info and warnings (#3326) * Add structured deprecation info and warnings Introduce a DLCDeprecationWarning and a DeprecationInfo pydantic model to standardize deprecation metadata (kind, target, replacement, since, removed_in, renamed params) with parsing and validation of versions. Revamp deprecated and renamed_parameter decorators to build messages from DeprecationInfo, emit DLCDeprecationWarning, attach metadata to wrapped callables (__deprecated_info__, __deprecated_params__), use ParamSpec/TypeVar typing for wrappers, and enforce error when both old and new kwargs are passed. Switch to packaging.version for version parsing. * Use DLCDeprecationWarning and add metadata tests Replace generic DeprecationWarning checks with DLCDeprecationWarning and import packaging.version.Version. Add tests verifying deprecated decorators attach metadata (including since/removed_in parsed as Version), validate invalid version inputs, and ensure removed_in > since. Also add tests for renamed_parameter behavior (conflicting old+new raises, metadata attachment, and invalid since handling) and small docstring/name preservation assertions. * Add packaging as core dep * guarantee unchanged behavior for deprecated `get_list_of_videos` and `list_videos_in_folder` * add warning if still unsupported extensions encountered * Consequently adjust `videotype` signatures of collect_video_path callers * refactor collect_video_paths: add warnings, raise for empty sequence. * update tests for collect_video_paths --------- Co-authored-by: Cyril Achard <cyril.achard@epfl.ch> Co-authored-by: Mackenzie Mathis <mathis@rowland.harvard.edu>
deruyter92
pushed a commit
that referenced
this pull request
May 15, 2026
* Add structured deprecation info and warnings Introduce a DLCDeprecationWarning and a DeprecationInfo pydantic model to standardize deprecation metadata (kind, target, replacement, since, removed_in, renamed params) with parsing and validation of versions. Revamp deprecated and renamed_parameter decorators to build messages from DeprecationInfo, emit DLCDeprecationWarning, attach metadata to wrapped callables (__deprecated_info__, __deprecated_params__), use ParamSpec/TypeVar typing for wrappers, and enforce error when both old and new kwargs are passed. Switch to packaging.version for version parsing. * Use DLCDeprecationWarning and add metadata tests Replace generic DeprecationWarning checks with DLCDeprecationWarning and import packaging.version.Version. Add tests verifying deprecated decorators attach metadata (including since/removed_in parsed as Version), validate invalid version inputs, and ensure removed_in > since. Also add tests for renamed_parameter behavior (conflicting old+new raises, metadata attachment, and invalid since handling) and small docstring/name preservation assertions. * Add packaging as core dep
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This small PR aims to help make the new deprecations module in #3303 easier to extend, better validated, and compatible with later automation efforts.
Note that unlike the original implementation, this is not the most lightweight deprecation system possible as it has external dependencies. If we prefer a lightweight deprecation system, this is not the solution.