Apache Beam Python 正则变换 Regex 完全指南：matches、find、replace 与 split 全解析

【免费下载链接】beamApache Beam is a unified programming model for Batch and Streaming data processing.项目地址https://gitcode.com/gh_mirrors/beam18/beam点击查看免费下载本文围绕 Apache Beam Python SDK 的元素级变换Regex展开基于仓库文档 regex.md 及其底层实现系统讲解 9 类正则处理能力从按正则过滤元素到提取分组、输出 KV 对、全局替换、按分隔符切分。读完本文你将能够在 Beam 管道中对PCollection[str]批量执行正则匹配、查找、替换与切分并理解每个方法在 util.py 中的真实实现机制与行为差异。一、Regex 变换是什么Regex是 Apache Beam Python SDK 提供的元素级Elementwise变换它接收一个字符串类型的PCollection基于正则表达式regular expression对每个元素进行过滤只保留匹配的元素并可选地基于匹配分组group对元素进行变换提取分组内容、生成键值对、替换或切分。在仓库中Regex定义于 sdks/python/apache_beam/transforms/util.py其 docstring 明确指出它是用于在PCollection中通过正则表达式处理元素的PTransform。它并不是一个需要import单独模块的类——在使用时直接通过beam.Regex.xxx调用即可例如import apache_beam as beam with beam.Pipeline() as pipeline: ( pipeline | Garden plants beam.Create([, Strawberry, perennial]) | Parse plants beam.Regex.matches(r(?Picon[^\s,]), *(\w), *(\w)) | beam.Map(print) )Regex下共提供 9 个静态方法全部是ptransform_fn装饰的变换函数可直接接到管道上方法作用锚定方式输入/输出类型matches(regex, group0)从字符串开头开始匹配保留匹配元素输出指定分组开头re.matchstr → strall_matches(regex)从开头匹配输出所有分组含整串 group 0组成的列表开头re.matchstr → List[str]matches_kv(regex, keyGroup, valueGroup0)从开头匹配按指定分组输出KV 对开头re.matchstr → Tuple[str, str]find(regex, group0)在字符串任意位置查找第一个匹配输出指定分组任意位置re.searchstr → strfind_all(regex, group0, outputEmptyTrue)查找所有匹配输出分组列表任意位置re.finditerstr → List[str]find_kv(regex, keyGroup, valueGroup0)查找所有匹配按分组输出KV 对列表任意位置re.finditerstr → Tuple[str, str]replace_all(regex, replacement)将正则匹配的所有出现替换为新字符串任意位置re.substr → strreplace_first(regex, replacement)仅替换第一处匹配任意位置re.sub(…, count1)str → strsplit(regex, outputEmptyFalse)按正则分隔符切分字符串任意位置re.splitstr → List[str]二、正则表达式基础与实用工具Regex底层依赖 Python 标准库re因此所有正则语法与 Python 的re模块完全一致。你可以在官方文档中查阅正则表达式语法也可以借助 regex101 这类在线工具编写和调试表达式——注意在侧边栏把 Flavor 切换为 Python以确保语法与re模块兼容。核心示例正则(?Picon[^\s,]), *(\w), *(\w)本文所有示例围绕同一个正则展开它把每行植物记录解析为三部分(?Picon[^\s,])命名分组icon。[^\s,]匹配任意不是空白字符\s等价于[ \t\n\r\f\v]也不是逗号,的连续字符直到遇到逗号为止。由于\s之外还匹配 Unicode 空白与符号因此该分组可以匹配 Emoji 等 utf-8 字符串例如。, *一个逗号后跟任意数量的空白字符。(\w)第二组匹配至少一个单词字符\w等价于[a-zA-Z0-9_]存入name对应的第 2 组。第三组(\w)同样匹配单词字符表示duration生长周期如perennial/annual/biennial。必须使用 raw string原始字符串为避免正则中的转义符被 Python 字符串解析意外吃掉文档明确建议使用原始字符串# 推荐r... 不会对反斜杠做二次转义 regex r(?Picon[^\s,]), *(\w), *(\w) # 不推荐普通字符串需要把 \w 写成 \\w极易出错 regex (?Picon[^\\s,]), *(\\w), *(\\w)关于 raw string 的语义可参考 Python 文档中字符串与字节字面量一节。三、从开头匹配的三种变换matches 系列Regex.matches、Regex.all_matches、Regex.matches_kv有一个共同特点正则从字符串开头开始匹配底层使用re.match。要实现匹配到字符串末尾需要在正则尾部追加$要从任意位置开始匹配则应改用find系列见第四节。示例 1Regex.matches—— 过滤并提取单个分组matches(regex, group0)保留所有匹配的元素并输出指定的分组group默认为0整个匹配也可以传分组编号如3或命名分组如icon。import apache_beam as beam # Matches a named group icon, and then two comma-separated groups. regex r(?Picon[^\s,]), *(\w), *(\w) with beam.Pipeline() as pipeline: plants_matches ( pipeline | Garden plants beam.Create([ , Strawberry, perennial, , Carrot, biennial ignoring trailing words, , Eggplant, perennial, , Tomato, annual, , Potato, perennial, # , invalid, format, invalid, , format, ]) | Parse plants beam.Regex.matches(regex) | beam.Map(print))输出与仓库测试 regex_test.py 中check_matches的期望一致, Strawberry, perennial , Carrot, biennial , Eggplant, perennial , Tomato, annual , Potato, perennial值得注意的两点行为细节元素, Carrot, biennial ignoring trailing words中biennial后还跟着ignoring trailing words依然被保留且输出整行——因为matches只要求从开头匹配成功并不要求匹配到末尾除非正则末尾有$。# , invalid, format以#开头第一个分组[^\s,]会匹配到#后遇到空格而停止紧接着要求,与\w但#后是空格而非逗号因此整体不匹配该元素被过滤掉invalid, , format中不是\w单词字符同样不匹配。源码层面util.pymatches内部对每个元素调用regex.match(element)匹配成功则yield m.group(group)并通过FlatMap输出——这正是每个元素可能产生 0 或 1 个输出的过滤语义。示例 2Regex.all_matches—— 输出全部分组all_matches(regex)同样从开头匹配但输出的是所有分组组成的列表。分组按在正则中出现的顺序排列且包含 group 0整个匹配作为第一个元素。import apache_beam as beam regex r(?Picon[^\s,]), *(\w), *(\w) with beam.Pipeline() as pipeline: plants_all_matches ( pipeline | Garden plants beam.Create([ , Strawberry, perennial, , Carrot, biennial ignoring trailing words, , Eggplant, perennial, , Tomato, annual, , Potato, perennial, # , invalid, format, invalid, , format, ]) | Parse plants beam.Regex.all_matches(regex) | beam.Map(print))输出对应测试 regex_test.py 的check_all_matches[, Strawberry, perennial, , Strawberry, perennial] [, Carrot, biennial, , Carrot, biennial] [, Eggplant, perennial, , Eggplant, perennial] [, Tomato, annual, , Tomato, annual] [, Potato, perennial, , Potato, perennial]实现上util.py该方法通过m.lastindex得知分组总数输出[m.group(ix) for ix in range(m.lastindex 1)]。需要输出全部匹配而非仅开头一处时应改用Regex.find_all(regex, groupRegex.ALL, outputEmptyFalse)。示例 3Regex.matches_kv—— 按分组输出键值对matches_kv(regex, keyGroup, valueGroup0)从开头匹配用正则的两个分组构造(key, value)二元组。keyGroup必填可以传分组编号如3或命名分组如iconvalueGroup默认为0整个匹配同样支持编号或命名分组。import apache_beam as beam regex r(?Picon[^\s,]), *(\w), *(\w) with beam.Pipeline() as pipeline: plants_matches_kv ( pipeline | Garden plants beam.Create([ , Strawberry, perennial, , Carrot, biennial ignoring trailing words, , Eggplant, perennial, , Tomato, annual, , Potato, perennial, # , invalid, format, invalid, , format, ]) | Parse plants beam.Regex.matches_kv(regex, keyGroupicon) | beam.Map(print))输出对应check_matches_kv见 regex_test.py(, , Strawberry, perennial) (, , Carrot, biennial) (, , Eggplant, perennial) (, , Tomato, annual) (, , Potato, perennial)这里keyGroupicon取命名分组而valueGroup缺省为0因此每个值都是完整匹配串。这种输出天然适合后续接GroupByKey、CombinePerKey等键值类变换。四、任意位置匹配的查找变换find 系列find系列与matches系列的核心差异在于锚定位置matches从字符串开头开始匹配re.match而find系列在字符串任意位置查找re.search/re.finditer。若希望find也严格从开头匹配可在正则前加^要匹配到末尾则加$。示例 4Regex.find—— 查找第一处匹配find(regex, group0)在字符串中查找第一个匹配并输出指定分组group默认0可传编号或命名分组。import apache_beam as beam regex r(?Picon[^\s,]), *(\w), *(\w) with beam.Pipeline() as pipeline: plants_matches ( pipeline | Garden plants beam.Create([ # , Strawberry, perennial, # , Carrot, biennial ignoring trailing words, # , Eggplant, perennial - , Banana, perennial, # , Tomato, annual - , Watermelon, annual, # , Potato, perennial, ]) | Parse plants beam.Regex.find(regex) | beam.Map(print))注意这里的输入每行以#前缀开头——matches会因开头不匹配而全部过滤掉而find因为可以跳过前缀、在任意位置匹配所以每个元素都能命中。输出与check_matches相同, Strawberry, perennial , Carrot, biennial , Eggplant, perennial , Tomato, annual , Potato, perennial示例 5Regex.find_all—— 查找全部匹配find_all(regex, group0, outputEmptyTrue)返回正则所有匹配的列表group默认0可传分组编号如3、命名分组如icon或传Regex.ALL以返回全部分组。outputEmpty默认True会输出无匹配元素的空列表项设为False则跳过无匹配的元素。import apache_beam as beam regex r(?Picon[^\s,]), *(\w), *(\w) with beam.Pipeline() as pipeline: plants_find_all ( pipeline | Garden plants beam.Create([ # , Strawberry, perennial, # , Carrot, biennial ignoring trailing words, # , Eggplant, perennial - , Banana, perennial, # , Tomato, annual - , Watermelon, annual, # , Potato, perennial, ]) | Parse plants beam.Regex.find_all(regex) | beam.Map(print))输出对应check_find_all见 regex_test.py[, Strawberry, perennial] [, Carrot, biennial] [, Eggplant, perennial, , Banana, perennial] [, Tomato, annual, , Watermelon, annual] [, Potato, perennial]可以看到# , Eggplant, perennial - , Banana, perennial一行中存在两处匹配与find_all会把两处都找出来而find只会返回第一处。这就是find_all相对find的核心价值。Regex.ALL的用法在 util.py 中ALL __regex_all_groups是一个哨兵常量。当group Regex.ALL时实现输出[(m.group(), m.groups()[0]) for m in matches …]即每个元素变成(整个匹配, 第一个分组)的元组列表。单元测试 util_test.py 验证了find_all(a(b*), util.Regex.ALL)会得到[[(ab, b), (ab, b), (ab, b)], …]这种全分组元组形态。示例 6Regex.find_kv—— 查找并输出键值对find_kv(regex, keyGroup, valueGroup0)查找字符串中所有匹配并分别用keyGroup/valueGroup指定的分组构造(key, value)输出。keyGroup必填valueGroup默认为0。import apache_beam as beam regex r(?Picon[^\s,]), *(\w), *(\w) with beam.Pipeline() as pipeline: plants_matches_kv ( pipeline | Garden plants beam.Create([ # , Strawberry, perennial, # , Carrot, biennial ignoring trailing words, # , Eggplant, perennial - , Banana, perennial, # , Tomato, annual - , Watermelon, annual, # , Potato, perennial, ]) | Parse plants beam.Regex.find_kv(regex, keyGroupicon) | beam.Map(print))输出对应check_find_kv见 regex_test.py——注意与、与各行都产出了两个KV 对(, , Strawberry, perennial) (, , Carrot, biennial) (, , Eggplant, perennial) (, , Banana, perennial) (, , Tomato, annual) (, , Watermelon, annual) (, , Potato, perennial)matches 与 find 系列如何选择需求选哪个原因只保留从开头符合格式的元素matches/all_matches/matches_kv开头锚定天然具备校验语义需要从头匹配且要匹配到串尾matches系列 正则尾部加$防止biennial ignoring trailing words这类半匹配通过要在任意位置抽取信息find/find_all/find_kv可跳过前缀等无关内容需要一处匹配还是全部匹配一处用find全部用find_all/find_kvfinditer会枚举所有匹配位置五、替换变换replace_all 与 replace_first示例 7Regex.replace_all—— 替换所有出现replace_all(regex, replacement)返回把所有匹配替换为replacement后的新字符串。替换串中支持使用反向引用backreferences例如用\1引用第一个分组的内容。import apache_beam as beam with beam.Pipeline() as pipeline: plants_replace_all ( pipeline | Garden plants beam.Create([ : Strawberry : perennial, : Carrot : biennial, \t:\tEggplant\t:\tperennial, : Tomato : annual, : Potato : perennial, ]) | To CSV beam.Regex.replace_all(r\s*:\s*, ,) | beam.Map(print))输出对应check_replace_all见 regex_test.py,Strawberry,perennial ,Carrot,biennial ,Eggplant,perennial ,Tomato,annual ,Potato,perennial注意输入中的\t:\tEggplant\t:\tperennial使用制表符\t包围冒号但正则\s*:\s*中的\s匹配一切空白空格、制表符等因此也能被统一规范化为 CSV 格式。此例正是把任意分隔形式归一化为统一格式的典型场景。示例 8Regex.replace_first—— 仅替换第一处replace_first(regex, replacement)只替换第一个匹配其余匹配保持原样。同样支持反向引用。import apache_beam as beam with beam.Pipeline() as pipeline: plants_replace_first ( pipeline | Garden plants beam.Create([ , Strawberry, perennial, , Carrot, biennial, ,\tEggplant, perennial, , Tomato, annual, , Potato, perennial, ]) | As dictionary beam.Regex.replace_first(r\s*,\s*, : ) | beam.Map(print))输出对应check_replace_first见 regex_test.py: Strawberry, perennial : Carrot, biennial : Eggplant, perennial : Tomato, annual : Potato, perennial每个元素都只把第一处,替换为:后面的,保持原样——这是把逗号分隔行改造成第一项: 其余字典风格格式的便捷手段。实现差异util.pyreplace_all直接调用regex.sub(replacement, elem)replace_first调用regex.sub(replacement, elem, 1)即re.sub的count1参数只替换一次。六、切分变换Regex.splitsplit(regex, outputEmptyFalse)按正则分隔符把字符串切分为字符串列表。outputEmpty默认False过滤掉切分产生的空字符串项设为True则保留空项例如连续分隔符之间产生的空串。import apache_beam as beam with beam.Pipeline() as pipeline: plants_split ( pipeline | Garden plants beam.Create([ : Strawberry : perennial, : Carrot : biennial, \t:\tEggplant : perennial, : Tomato : annual, : Potato : perennial, ]) | Parse plants beam.Regex.split(r\s*:\s*) | beam.Map(print))输出对应check_split见 regex_test.py[, Strawberry, perennial] [, Carrot, biennial] [, Eggplant, perennial] [, Tomato, annual] [, Potato, perennial]split的实现util.py先调用regex.split(element)再在outputEmptyFalse时执行list(filter(None, r))剔除空串。单元测试 util_test.py 对两种模式都有覆盖split(\\s, True)会保留连续空格间的空项而split(\\s, False)得到纯净的单词列表。七、源码实现原理9 个方法的共同骨架所有 9 个方法共享同一套设计util.py统一编译正则静态方法_regex_compile(regex)util.py判断入参是字符串还是re.compile后的 pattern 对象——两个类型都接受。单元测试中的test_find_pattern、test_match_pattern、test_split_pattern等util_test.py专门验证了预编译 pattern 的用法。类型约束每个方法都用typehints.with_input_types(str)声明输入必须是str并用with_output_types声明输出类型str/List[str]/Tuple[str, str]供 Beam 的类型检查器在运行时校验。变换语义除replace_all/replace_first用Map做 1:1 映射外其余方法都用FlatMap包裹内部生成器函数——匹配失败的元素 yield 不出任何值从而被自然过滤匹配成功则可 yield 一个或多个值如find_kv对每个匹配位置各 yield 一个 KV 对。底层依赖的re方法映射如下理解它就能预测行为Regex 方法底层 re 调用语义matches/all_matches/matches_kvre.match仅从头开始匹配findre.search任意位置首个匹配find_all/find_kvre.finditer任意位置全部匹配replace_allre.sub全局替换replace_firstre.sub(…, count1)只替换一次splitre.split按分隔符切分八、完整参数速查表参数适用方法取值默认值regex全部正则字符串或re.compile的 pattern必填groupmatches/find/find_all分组编号如3、命名分组如icon、find_all额外支持Regex.ALL0整个匹配keyGroupmatches_kv/find_kv分组编号或命名分组用作 key必填valueGroupmatches_kv/find_kv分组编号或命名分组用作 value0整个匹配replacementreplace_all/replace_first替换字符串支持反向引用必填outputEmptyfind_all/split布尔值是否输出/保留空项find_all为Truesplit为False关于空项参数有一处容易混淆再次强调find_all的outputEmpty默认True无匹配的元素输出空列表[]而split的outputEmpty默认False过滤切分产生的空串。若需要仅保留有匹配的元素请显式传find_all(regex, outputEmptyFalse)。九、可继续阅读的相关变换Regex在文档体系中归属元素级变换Elementwise transforms与其关系最密切的两个兄弟变换是FlatMap 变换对每个输入元素可能产生零个或多个输出——Regex内部正是借助FlatMap实现匹配失败即过滤的。Map 变换对每个元素执行简单的 1:1 映射函数——replace_all/replace_first即基于Map实现。十、测试与验证如果你希望验证本文所有示例的行为仓库中提供了两层测试证据示例级测试regex_test.py 通过 mockprint捕获输出逐一断言 9 个示例的期望结果即上文展示的输出。单元级测试util_test.py 的RegexTest覆盖了更细粒度的行为包括预编译 pattern 入参test_find_pattern等、命名分组提取test_find_group_name、空匹配过滤test_find_empty/test_match_none、find_all的Regex.ALL与outputEmpty组合test_find_all_groups、split保留/过滤空项test_split_with_empty/test_split_without_empty等可作为理解各参数语义的权威参考。小结Regex是 Beam Python 管道中处理文本格式最直接的一站式工具——matches系列负责开头格式校验与分组提取find系列负责任意位置抽取全部信息replace系列负责文本规范化split负责按分隔符拆解字段。结合$/^锚定、命名分组与outputEmpty参数几乎可以覆盖日志解析、数据清洗、字段抽取等绝大多数字符串处理需求。赞分享【免费下载链接】beamApache Beam is a unified programming model for Batch and Streaming data processing.项目地址https://gitcode.com/gh_mirrors/beam18/beam点击查看免费下载相关推荐pi-web数据库设计会话数据存储的最佳实践指南pi web数据库设计会话数据存储的最佳实践指南 pi web作为pi编程智能体的本地网页界面其核心功能在于高效管理和持久化会话数据。本文将深入解析pi wLint代码质量Apache Beam Mean 聚合变换完全指南全局均值与按 Key 分组均值Java / Python / GoApache Beam Mean 聚合变换完全指南全局均值与按 Key 分组均值Java / Python / Go 本文以 Apache Beam 官方批处理流处理大数据SeaTunnel Replace 转换插件完全指南字符串字面量与正则替换实战SeaTunnel Replace 转换插件完全指南字符串字面量与正则替换实战 本文以 SeaTunnel 仓库中的 Replace 转换插件文档 https数据集成ETL大数据批处理流处理变更数据捕获上一篇LitePal与Dagger单例数据库管理下一篇repowise 的 claude_cli LLM Provider用本地 Claude Code CLI 驱动文档生成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考