{"record":{"id":"66754aee9c8e12d9","repo":"apache/beam","slug":"name","errorCode":null,"errorMessage":"%name%","messagePattern":"%name%","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"sdks/python/apache_beam/utils/annotations.py","lineNumber":120,"sourceCode":"    else:\n      if label == 'deprecated' and '%since%' not in custom_message:\n        raise TypeError(\n            \"Replacement string %since% not found on \\\n        custom message\")\n      emptyArg = lambda x: '' if x is None else x\n      message = custom_message\\\n      .replace('%since%', emptyArg(since))\\\n      .replace('%current%', emptyArg(current))\\\n      .replace('%extra%', emptyArg(extra_message))\n    self.label = label\n    self.message = message\n\n  def emit_warning(self, fnc_name):\n    if self.label == 'deprecated':\n      warning_type = BeamDeprecationWarning\n    else:\n      warning_type = FutureWarning\n    warnings.warn(\n        self.message.replace('%name%', fnc_name), warning_type, stacklevel=3)\n\n\ndef annotate(label, since, current, extra_message, custom_message=None):\n  \"\"\"Decorates an API with a deprecated or experimental annotation.\n\n  Args:\n    label: the kind of annotation ('deprecated' or 'experimental').\n    since: the version that causes the annotation.\n    current: the suggested replacement function.\n    extra_message: an optional additional message.\n    custom_message: if the default message does not suffice, the message\n      can be changed using this argument. A string\n      whit replacement tokens.\n      A replecement string is were the previus args will\n      be located on the custom message.\n      The following replacement strings can be used:\n      %name% -> API.__name__","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/utils/annotations.py#L102-L138","documentation":"emit_warning is the generic deprecation/experimental notice emitter in apache_beam.utils.annotations. For an annotation labeled 'deprecated' it emits BeamDeprecationWarning, otherwise FutureWarning, replacing the %name% placeholder in the annotation's message template with the actual function name, at stacklevel=3 to point at the caller.","triggerScenarios":"Calling any Beam API decorated with @annotate('deprecated', ...) or @annotate('experimental', ...) — e.g. older Map/FlatMap-style helpers — triggers this warning with the decorated function's name substituted for %name%.","commonSituations":"Upgrading Beam versions: code written against an API deprecated in a prior release still works but now warns; CI logs fill with BeamDeprecationWarning/FutureWarning.","solutions":["Read the warning to identify the deprecated function and switch to the 'current' replacement named in the annotation (the annotate decorator documents it).","Check the Beam migration guide for the deprecated API's successor and update call sites.","If migration must be deferred, suppress selectively: warnings.filterwarnings('ignore', category=BeamDeprecationWarning).","Pin the current Beam version temporarily if you cannot migrate yet (deprecated APIs are eventually removed)."],"exampleFix":"// before\nbeam.FlatMapTuple(lambda kv: [kv])  # deprecated helper\n// after\nbeam.FlatMap(lambda kv: [kv])","handlingStrategy":"try-catch","validationCode":"# Detect deprecated API usage in CI\npython -W error::FutureWarning your_pipeline.py","typeGuard":null,"tryCatchPattern":"import warnings\nfrom apache_beam.utils.annotations import BeamDeprecationWarning\nwith warnings.catch_warnings():\n    warnings.filterwarnings('ignore', category=BeamDeprecationWarning)\n    legacy_call()","preventionTips":["Run CI with -W error::FutureWarning to fail on deprecated API usage","Read the annotate decorator's 'current' argument to find replacements","Review Beam release notes when upgrading"],"tags":["deprecation","api-migration","futurewarning"],"backgroundTag":"deprecated-api-usage","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}