Prepare TensorFlow deprecation - add `deeplabcut.api` by deruyter92 · Pull Request #3382 · DeepLabCut/DeepLabCut

deruyter92 · 2026-06-26T16:17:12Z

Preparation for full TensorFlow deprecation

Remove deeplabcut.compat and split into PyTorch-only deeplabcut.api and TF-only deeplabcut.tensorflow_compat
Add TensorFlow routing and deprecation utilities which warns the user.

Background

TensorFlow support will be dropped soon and a clean preparation is needed to make the transition smooth. Although the pose_estimation code was already cleanly branched in deeplabcut/compat.py, this brought the disadvantage that the main entrypoint for DeepLabCut is actually mixed API, which was not ideal to test and remains a small obstacle to eventually remove TF cleanly.

This PR makes a large step towards clean TF deprecation, by splitting the compat module into our new clean user-facing API (Pytorch-only) with a fallback for TensorFlow instead of mixed API. It introduces some new packages and removes deeplabcut.compat as the entry point for the public API.

New

deeplabcut.api : the new home for user-facing API functions. Currently covers all pose estimation functions (train_network, evaluate_network, analyze_videos, analyze_images, etc.), but can cover other main API as well.

deeplabcut.tensorflow_compat — an isolated compatibility layer that holds the TensorFlow-specific branches, split out of compat.py. This module is explicitly marked as temporary and will be deleted wholesale when TF support is dropped.

deeplabcut.api._tf_routing — a new decorator-based routing system (@with_tensorflow_fallback) that automatically intercepts calls to functions in deeplabcut.api, resolves the engine and delegates to deeplabcut.tensorflow_compat handling TF-only legacy kwargs. A DLCDeprecationWarning is emitted to inform user about the migration.

Next steps

This PR intentionally scopes to pose estimation only. (I included generate_training_dataset as well first, it's probably better to work in incremental changes, rather than one big PR).

Several other areas still go through compat or have TF branches inline and need similar treatment in follow-up PRs:

Dataset creation (generate_training_dataset) — the largest remaining concern.
deeplabcut.utils — scattered TF-conditional helpers.
deeplabcut.modelzoo — TF-specific download / inference paths.
Other smaller callsites in the GUI and 3D/tracking modules.

The goal is that every user-facing function ultimately lives under deeplabcut.api with a clean, PyTorch-only signature, while all TF code is quarantined in deeplabcut.tensorflow_compat and removable in a single future commit.

Test coverage

tests/api/test_pose_estimation.py (480 lines) — smoke tests for the new deeplabcut.api pose estimation surface: parameter forwarding, engine routing, legacy kwarg handling.
tests/api/test_tf_routing.py (360 lines) — unit tests for the _tf_routing machinery: engine resolution, renamed/dropped param warnings, gputouse normalisation, multi-shuffle validation.
tests/core/test_visualization.py (191 lines) — new coverage for deeplabcut.core.visualization helpers.
tests/pose_estimation_pytorch/apis/test_apis_utils.py (102 lines) — new coverage for PyTorch API utilities.

deruyter92 · 2026-06-29T07:17:57Z

(Needs formatted docstrings and typed configs still)

…utouse

… GUI + misc)

…low_compat

…orflow copy)

…lder

C-Achard

Good start,I really like the design overall, I just think some of the current routing might need to be made safer; happy to discuss if needed!

Apply `renamed_params` aliases (e.g., `cfg_path` → `config`) to the bound `unified` dict before `_resolve_engine` and `when` inspect it, so they always see canonical parameter names.

deruyter92 · 2026-07-17T15:31:35Z

@C-Achard thanks for your review. I've made the tf_routing more robust now. I've addressed all your comments, and added more tests.

I will do another iteration next week to see if there are more tests to be added, and try it out in practice a low. It is a high-impact PR, so I agree that it should be well-tested.

…h path

…d stale references

…recation

C-Achard

Just a few preliminary comments while going through this again, let's perhaps discuss which areas would benefit from further review/testing as it has grown quite a bit.

C-Achard · 2026-08-10T10:00:05Z



-@deprecated(replacement="deeplabcut.core.config.ProjectConfig", since="3.1")
+@deprecated(replacement="deeplabcut.core.config.ProjectConfig", since="3.0.1")


A small question/design curiosity when I see this, should we have a file that defines several consts with version numbers mapping to deprecation, so that whenever there is a round of deprecating something, there is one single source for the version, minimizing the need to globally search for version numbers, and avoiding changing version numbers for an unrelated round of deprecation or on the wrong API?

C-Achard · 2026-08-10T10:03:05Z

    def __init__(self, root, parent, h1_description):
        super().__init__(root, parent, h1_description)
+
+        self._reload_timer = QTimer(self)


Should these defs be moved to the base class?

C-Achard · 2026-08-10T10:03:36Z

    def __init__(self, root, parent, h1_description):
        super().__init__(root, parent, h1_description)

+        self._reload_timer = QTimer(self)


As mentioned elsewhere, might be best moved to the base class instead ? Even if disabled by default

C-Achard assigned deruyter92 and C-Achard Jun 26, 2026

C-Achard added the Tensorflow 2 label Jun 26, 2026

C-Achard modified the milestones: v3.0.1, TensorFlow deprecation Jun 26, 2026

deruyter92 added 23 commits July 16, 2026 18:40

unsilence DLCDeprecationWarning: show once per instance

1e87182

add modules deeplabcut.api and deeplabcu.tensorflow_compat (init only)

b8822a9

add tensorflow routing for deprecated tensorflow API

43f7c13

copy compat into tensorflow_compat/tensorflow_api

76cae98

update _tf_routing: resolve deprecated arguments

637d6dd

update _tf_routing.py: improve engine resolution

209d6af

copy compat into api/pose_estimation

bf741d6

remove docstings in pose_estimation.py

b9698f5

temp clean pose_estimation_api

22a14ab

update _tf_routing: require dropped, renamed params, and normalize gp…

c9a61d0

…utouse

add canoncical pose estimation API with TF fallback

4693f3a

update tensorflow API in tensorflow_compat

8ce0737

fix Engine imports across repo (core, not compat)

58a1af7

hook up deeplabcut.api.pose_estimation instead of compat (main init +…

7d68c6a

… GUI + misc)

add tests for _tf_routing

960196b

generate_training_dataset: update Engine import (until not needed)

a4e7d60

remove TensorFlow branches in generate_training_dataset

7992a28

copy TensorFlow-only branches of generate_training_dataset to tensorf…

7fe518d

…low_compat

remove engine parameter in generate_training_dataset (and in the tens…

e18feeb

…orflow copy)

adjust tf_routing: import top-level tensorflow_compat

88072ba

fix rename_parameter order in evaluate_network API

d487333

hook up data_management / generate_training_dataset API

dad9af5

deeplabcut.api.pose_estimation fix incorrect dropped parameter destfo…

66cddae

…lder

use centralized yaml loading / writing

c32222a

deruyter92 marked this pull request as ready for review July 17, 2026 11:07

C-Achard reviewed Jul 17, 2026

View reviewed changes

Comment thread deeplabcut/api/_tf_routing.py Outdated

C-Achard reviewed Jul 17, 2026

View reviewed changes

Comment thread deeplabcut/api/_tf_routing.py Outdated

C-Achard reviewed Jul 17, 2026

View reviewed changes

deruyter92 added 6 commits July 17, 2026 16:08

fix when predicate for tf routing: use unified args

32bf556

fix falsey gputouse

6e5cf5b

copy dict for _resolve_legacy_kwargs

e810dc0

fix(tf_routing): normalize renamed params before engine resolution

e8a1083

Apply `renamed_params` aliases (e.g., `cfg_path` → `config`) to the bound `unified` dict before `_resolve_engine` and `when` inspect it, so they always see canonical parameter names.

pop "engine" from unified

c27cce0

add tests for TF routing

8d9ee1b

fix test_tf_routing: should NOT warn deprecation for canonical pytorc…

900c593

…h path

deruyter92 marked this pull request as draft July 28, 2026 18:10

deruyter92 modified the milestones: TensorFlow deprecation, Refresh core API and interface Jul 30, 2026

deruyter92 mentioned this pull request Aug 9, 2026

Add detector_eval_interval to train_from_coco #3436

Open

deruyter92 added 8 commits August 9, 2026 14:21

improve docstrings

16766bf

update TF compat: raise warning for ignored PT-only parameters

dbaae74

remove torch_kwargs from tf-only branch

78dccec

fix circular import risk

bdd0692

remove lru_cache decorator: it had no performance benefits, but riske…

f739124

…d stale references

add tests for routing to TF

e0f8c7f

add tests for _positionals_as_kwargs

1ace271

Merge remote-tracking branch 'upstream/main' into jaap/prepare_tf_dep…

8242596

…recation

deruyter92 requested a review from C-Achard August 10, 2026 09:24

deruyter92 marked this pull request as ready for review August 10, 2026 09:24

C-Achard reviewed Aug 10, 2026

View reviewed changes

deruyter92 changed the base branch from main to feat/refreshed-api August 12, 2026 14:59

C-Achard self-requested a review August 13, 2026 13:50



		@deprecated(replacement="deeplabcut.core.config.ProjectConfig", since="3.1")
		@deprecated(replacement="deeplabcut.core.config.ProjectConfig", since="3.0.1")

Uh oh!

Uh oh!

Conversation

deruyter92 commented Jun 26, 2026

Preparation for full TensorFlow deprecation

Background

New

Next steps

Test coverage

Uh oh!

deruyter92 commented Jun 29, 2026

Uh oh!

Uh oh!

Uh oh!

C-Achard left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

deruyter92 commented Jul 17, 2026

Uh oh!

C-Achard left a comment

Choose a reason for hiding this comment

Uh oh!

C-Achard Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

C-Achard Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

C-Achard Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants