{"record":{"id":"3fb11491d55361ae","repo":"PaddlePaddle/PaddleOCR","slug":"the-function-replace-sub-is-deprecated-please","errorCode":null,"errorMessage":"The function 'replace_sub()' is deprecated, please use 'upgrade_sublayer()' instead.","messagePattern":"The function 'replace_sub\\(\\)' is deprecated, please use 'upgrade_sublayer\\(\\)' instead\\.","errorType":"exception","errorClass":"DeprecationWarning","httpStatus":null,"severity":"warning","filePath":"ppocr/modeling/backbones/rec_pphgnetv2.py","lineNumber":562,"sourceCode":"            return_patterns = stages_pattern\n        # return_stages is int or bool\n        if type(return_stages) is int:\n            return_stages = [return_stages]\n        if isinstance(return_stages, list):\n            if max(return_stages) > len(stages_pattern) or min(return_stages) < 0:\n                return_stages = [\n                    val\n                    for val in return_stages\n                    if val >= 0 and val < len(stages_pattern)\n                ]\n            return_patterns = [stages_pattern[i] for i in return_stages]\n\n        if return_patterns:\n            self.update_res(return_patterns)\n\n    def replace_sub(self, *args, **kwargs) -> None:\n        msg = \"The function 'replace_sub()' is deprecated, please use 'upgrade_sublayer()' instead.\"\n        raise DeprecationWarning(msg)\n\n    def upgrade_sublayer(\n        self,\n        layer_name_pattern: Union[str, List[str]],\n        handle_func: Callable[[nn.Layer, str], nn.Layer],\n    ) -> Dict[str, nn.Layer]:\n        \"\"\"use 'handle_func' to modify the sub-layer(s) specified by 'layer_name_pattern'.\n\n        Args:\n            layer_name_pattern (Union[str, List[str]]): The name of layer to be modified by 'handle_func'.\n            handle_func (Callable[[nn.Layer, str], nn.Layer]): The function to modify target layer specified by 'layer_name_pattern'. The formal params are the layer(nn.Layer) and pattern(str) that is (a member of) layer_name_pattern (when layer_name_pattern is List type). And the return is the layer processed.\n\n        Returns:\n            Dict[str, nn.Layer]: The key is the pattern and corresponding value is the result returned by 'handle_func()'.\n\n        Examples:\n\n            from paddle import nn","sourceCodeStart":544,"sourceCodeEnd":580,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/ppocr/modeling/backbones/rec_pphgnetv2.py#L544-L580","documentation":"rec_pphgnetv2 defines replace_sub() as a hard-removed deprecated API: calling it always raises DeprecationWarning with instructions to use upgrade_sublayer(). upgrade_sublayer(self, layer_name_pattern, handle_func) applies handle_func(layer, pattern) to each matching sublayer and returns the modified layers — it is the drop-in replacement. Note Python only treats DeprecationWarning specially when raised as a warning via warnings.warn; here it is raised as an exception, so it always aborts.","triggerScenarios":"Calling backbone.replace_sub('conv', fn) or replace_sub(segments, fn) on a PPHGNetV2 backbone instance; typical when porting FP16/reparam hooks or channel-pruning scripts written against older PaddleOCR/PaddleX layer APIs.","commonSituations":"Upgrading PaddleOCR and re-running an old quantization/pruning script that used replace_sub; code copied from another backbone class where replace_sub still exists as a working Paddle API.","solutions":["Replace the call: backbone.upgrade_sublayer(layer_name_pattern, handle_func) — same semantics, returns Dict[str, nn.Layer]","Update any helper utilities that branch on hasattr(model, 'replace_sub') to also prefer upgrade_sublayer"],"exampleFix":"# before\nmodel.backbone.replace_sub(r'.*conv', lambda layer, name: replace_with_fp16(layer))\n\n# after\nmodel.backbone.upgrade_sublayer(r'.*conv', lambda layer, name: replace_with_fp16(layer))","handlingStrategy":"fallback","validationCode":"replace = getattr(backbone, 'upgrade_sublayer', None) or getattr(backbone, 'replace_sub', None)\nassert replace is not None, 'no sublayer-replacement API available'\nreplace(pattern, handle_func)","typeGuard":"def sublayer_api(backbone):\n    return getattr(backbone, 'upgrade_sublayer', None) or getattr(backbone, 'replace_sub', None)","tryCatchPattern":"try:\n    backbone.replace_sub(pattern, fn)\nexcept DeprecationWarning:\n    backbone.upgrade_sublayer(pattern, fn)","preventionTips":["Target upgrade_sublayer directly; it exists on current PPHGNetV2","Pin your PaddleOCR version in lockfiles so API removals don't surprise scripts","Centralize layer-rewriting helpers in one module so migrations touch one place"],"tags":["deprecation","api-migration","backbone","pphgnet"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}