jc 解析器深入：使用 `jc --ini-dup` 保留 INI 重复键值的 JSON 转换指南

开发工具【免费下载链接】jcCLI tool and python library that converts the output of popular command-line tools, file-types, and common strings to JSON, YAML, or Dictionaries. This allows piping of output to tools like jq and simplifying automation scripts.项目地址https://gitcode.com/gh_mirrors/jc/jc点击查看免费下载导读INI 是系统与应用配置中最常见的文本格式之一但标准 INI 解析器如 Pythonconfigparser的默认行为遇到重复键时只保留最后一个值容易丢失信息。jc 项目提供的ini_dup解析器专门解决这一问题它解析标准 INI 文件并把所有值都放进列表/数组从而完整保留重复键的每一个取值。本文以 docs/parsers/ini_dup.md 为主体结合 ini_dup.py 源码与 test_ini_dup.py 测试用例讲解该解析器的语法规则、CLI 与 Python 模块两种用法、输出 Schema以及它与普通ini解析器的差异读完后你可以直接用jc --ini-dup处理多值配置并接入jq等管道工具。一、ini_dup 是什么为“多值配置”而生的解析器jc是一个把命令行工具输出、文件类型和常见字符串转换为 JSON / YAML / 字典的 CLI 工具与 Python 库。绝大多数 INI 解析器包括 Python 标准库configparser的默认字典类型在遇到重复键时只保留最后一个值而ini_dup反其道而行它在解析时保留全部重复值并把每个键的值统一包装为列表list/array即使该键只有一个值也是如此。这一点从解析器的元信息可以确认——ini_dup.py 中的info类声明class info(): Provides parser metadata (version, author, etc.) version 1.2 description INI with duplicate key file parser author Kelly Brazil author_email kellyjonbrazilgmail.com details Using configparser from the python standard library compatible [linux, darwin, cygwin, win32, aix, freebsd] tags [standard, file, string]可以看到底层实现基于Python 标准库configparserdetails字段兼容平台包括 linux、darwin、cygwin、win32、aix、freebsdcompatible字段标签为standard、file、string即属于“标准文件/字符串解析器”既可解析配置文件也可直接解析字符串内容。值得留意的是ini_dup的核心逻辑还被kv_dup解析器复用在 kv_dup.py 中可以看到kv_dup被实现为ini_dup的别名This parser is an alias of ini_dup.py这印证了ini_dup在 jc 解析器体系中承担着“重复键保留”的通用基础职责。二、解析语法规则五种关键行为原文档对解析规则作了明确界定以下逐条展开并结合源码印证1. 分隔符或:均可INI 行的键值分隔符既可以是等号也可以是冒号:。测试用例 test_ini_dup.py 中混合使用了两种分隔符[section] duplicate_key: value1 another_key foo duplicate_key value2解析结果为{section:{duplicate_key:[value1,value2],another_key:[foo]}}可见两种分隔符可以混用于同一文件且键名大小写会被原样保留。2. 缺失值key-only支持形如skip_external_locking这种只有键没有值的行是合法的解析后该键对应的值列表为[]含一个空字符串。这一行为由两点共同保证解析器构造时设置了allow_no_valueTrueini_dup.py自定义的MultiDict.__setitem__会把None值转为[]ini_dup.py。测试用例test_ini_dup_single_key_no_valuetest_ini_dup.py验证了这一点[data] novalue{data:{novalue:[]}}真实的 MariaDB 配置 fixtureini-mariadb.ini中的skip_external_locking行在输出ini-dup-mariadb.json中也体现为skip_external_locking:[]。3. 注释#或;前缀且必须独占一行注释前缀支持#和;两种但注释必须单独成行不能出现在键值行末尾。这与configparser的标准行为一致也是 INI 语法本身的一个硬性限制。4. 顶层键与节section名冲突顶层键被覆盖如果某个节section的名字与某个顶层键同名该顶层键会被节的字典数据覆盖。因此在设计输出 Schema 时顶层键与节名必须互不冲突。5. 多行值每行一个列表项不支持空行如果某个键的值跨越多行每一行都会成为值列表中的一个独立条目。需要注意多行值中间的空行不被支持。这一点对应源码中的empty_lines_in_valuesFalse设置ini_dup.py说明空行会被视为值的中止。引号处理重要 Note原文档特别强调以双引号或单引号开头并结尾的值引号会被自动剥离。例如passwordbar会解析为[bar]而不是[\bar\]。如果希望保留引号有两个途径CLI 使用-rraw参数模块调用使用parse(data, rawTrue)。引号剥离在_process阶段完成ini_dup.py它遍历所有顶层值与节内值对每个值调用jc.utils.remove_quotes。该工具函数utils.py的逻辑是仅当字符串同时以或开头且结尾时才去掉首尾各一个字符否则原样返回def remove_quotes(data: str) - str: if data.startswith() and data.endswith(): data data[1:-1] elif data.startswith() and data.endswith(): data data[1:-1] return data这一点也有专门的测试与 fixture 支撑双引号文件 ini-double-quote.ini 中passwordbar输出为[bar]见 ini-dup-double-quote.json单引号文件 ini-single-quote.ini 同样输出[bar]见 ini-dup-single-quote.json。三、两种使用方式CLI 与 Python 模块CLI 用法原文档给出最基本的调用方式$ cat foo.ini | jc --ini-dupjc 的 CLI 会把解析器短名称中的下划线替换为连字符见 cli.py 的parser_shortname因此ini_dup对应的命令行参数是--ini-dup。-p参数可以让输出更易读pretty-print$ cat example.ini | jc --ini-dup -pPython 模块用法在 Python 代码中通过jc.parse调用import jc result jc.parse(ini_dup, ini_file_output)其中ini_file_output是包含 INI 文本的字符串。parse函数签名ini_dup.py为def parse(data, rawFalse, quietFalse): Parameters: data: (string) text data to parse raw: (boolean) unprocessed output if True quiet: (boolean) suppress warning messages if True Returns: Dictionary representing the INI file. 三个参数的含义data待解析的 INI 文本字符串raw为True时返回未加工的输出即保留引号、保留原始结构quiet为True时抑制警告信息例如跨平台兼容性提示。parse开头还会做两件事调用jc.utils.compatibility()检查当前平台是否在兼容列表内不兼容时给出警告quietTrue可屏蔽以及调用jc.utils.input_type_check()校验输入类型。四、输出 Schema一切皆列表原文档给出了完整的输出结构{ key1: [ string ], key2: [ string ], section1: { key1: [ string ], key2: [ string ] } }核心要点顶层键无节包裹值为字符串列表每个节section映射为一个字典节内的每个键同样对应字符串列表该结构“与 Pythonconfigparser标准库文档的描述一致”原文档原话区别仅在于重复键被完整保留而非覆盖。完整示例原文档自带示例文件example.inifoo fiz bar buz [section1] fruit apple color blue color red [section2] fruit pear fruit peach color green执行jc --ini-dup -p后输出{ foo: [ fiz ], bar: [ buz ], section1: { fruit: [ apple ], color: [ blue, red ] }, section2: { fruit: [ pear, peach ], color: [ green ] } }观察重点color blue与color red两个重复键在section1中变成[blue, red]fruit pear与fruit peach在section2中变成[pear, peach]即使foo、bar只有一个值也以单元素列表呈现。五、源码级原理MultiDict 与 configparser 的协作ini_dup与普通ini解析器ini.py最大的实现差异在于自定义的字典类型MultiDictini_dup.pyclass MultiDict(dict): # https://stackoverflow.com/a/38286559/12303989 def __setitem__(self, key, value): if value is None: self[key] [] if key in self: if isinstance(value, list): self[key].extend(value) elif isinstance(value, str): if len(self[key]) 1: return else: super().__setitem__(key, value)其行为可概括为三条分支值为None即缺失值/无值键存入空字符串列表[]键已存在若新值是列表则追加合并extend若是字符串则仅当现有列表长度为 1 时才追加避免重复合并造成翻倍键不存在走默认的dict.__setitem__。随后在parse中该字典被注入configparser.ConfigParserini_dup.pyini_parser configparser.ConfigParser( dict_typeMultiDict, allow_no_valueTrue, interpolationNone, default_sectionNone, empty_lines_in_valuesFalse, strictFalse ) # dont convert keys to lower-case: ini_parser.optionxform lambda option: option关键参数逐一说明dict_typeMultiDict让configparser在写入选项值时调用MultiDict.__setitem__从而保留重复值allow_no_valueTrue允许key单独成行无/:与值interpolationNone禁用%插值防止配置值中的%被误解析default_sectionNone禁用名为[DEFAULT]的全局默认节特殊语义注意这与普通ini解析器一致[DEFAULT]仍会作为普通节输出见下文 fixtureempty_lines_in_valuesFalse多行值中不保留空行对应原文档规则 5strictFalse允许重复键而不抛DuplicateOptionErroroptionxform lambda option: option不把键名转成小写保持原始大小写。无节文本的兜底处理configparser要求文本必须至少有一个节[section]否则抛出configparser.MissingSectionHeaderError。ini_dup的处理方式是ini_dup.py生成一个不会与原文冲突的 UUID 作为临时节名把整个输入包裹成[my_uuid]节重新解析然后把临时节的内容“提升”回根层级再合并其余真实节。这就是为什么example.ini中foo、bar能成为顶层键而不是被塞进某个节里。六、实战对比ini_dup 与 ini仓库中同时存在普通 INI 解析器iniini.py与ini_dup二者的核心差异就是重复键的处理策略对比维度jc --ini普通jc --ini-dup保留重复重复键只保留最后一个值全部保留合并进列表单值键输出字符串如fiz单元素列表如[fiz]缺失值输出空字符串[]适用场景标准单值配置多值/可重复键配置原文档对普通ini的说明是“如果发现重复键只使用最后一个值”见 ini.py 的文档字符串。举例来说同一份含重复color的配置普通ini只输出color: red而ini_dup输出color: [blue, red]。真实配置文件案例MariaDB my.cnf仓库的测试 fixture 提供了非常贴近实战的案例——Debian 风格的 MariaDB 配置文件 ini-mariadb.ini其中包含大量真实参数。经ini_dup解析后ini-dup-mariadb.json可以得到{ server: {}, mysqld: { user: [mysql], pid_file: [/var/run/mysqld/mysqld.pid], port: [3306], datadir: [/var/lib/mysql], skip_external_locking: [], key_buffer_size: [16M], max_allowed_packet: [64M], max_connections: [80], innodb_buffer_pool_size: [1G], character_set_server: [utf8mb4], collation_server: [utf8mb4_general_ci] }, embedded: {}, mariadb: { performance_schema: [ON], performance_schema_instrument: [stage/%ON] }, mariadb-10.1: {} }这个案例演示了三个实战要点带#注释的完整系统配置文件可以整体转换注释被自动忽略skip_external_locking这类无值布尔开关变成[]**空节如[server]、[embedded]**输出为空字典{}所有参数值统一为字符串列表方便后续用jq统一处理。另一个 fixture 是 SSH 风格的配置 ini-test.ini其输出ini-dup-test.json为{ DEFAULT: { ServerAliveInterval: [45], Compression: [yes], CompressionLevel: [9], ForwardX11: [yes] }, bitbucket.org: { User: [hg] }, topsecret.server.com: { Port: [50022], ForwardX11: [no] } }注意由于default_sectionNone[DEFAULT]节被当作普通节输出到顶层并未将其内容注入其他节。七、用 jq 消费 ini_dup 的输出由于所有值都是数组ini_dup 的输出与jq配合非常自然。例如对上面的 SSH 配置可以$ cat ssh_config.ini | jc --ini-dup | jq .topsecret.server_com.Port[0] 50022在需要“每个键的完整取值集合”的场景如收集某参数的多次出现、对比配置差异、审计重复配置项中列表结构让下游脚本无需担心丢值。八、注意事项与限制小结综合原文档与源码使用ini_dup时请牢记以下约束注释必须独占一行行尾注释不会被识别多行值不支持空行empty_lines_in_valuesFalse顶层键与节名冲突时顶层键被覆盖应避免同名引号会被剥离保留需用-r/rawTrue所有值无论是否重复都以列表形式返回处理单值时记得取[0]或使用 jq 的数组操作空数据输入返回空字典{}见 test_ini_dup.py 的test_ini_dup_nodata用例。九、相关资源导航解析器文档docs/parsers/ini_dup.md解析器源码jc/parsers/ini_dup.py普通 INI 解析器对照jc/parsers/ini.py别名解析器 kv_dupjc/parsers/kv_dup.py单元测试tests/test_ini_dup.py测试 fixturetests/fixtures/generic/ini-test.ini 与 tests/fixtures/generic/ini-dup-test.jsontests/fixtures/generic/ini-mariadb.ini 与 tests/fixtures/generic/ini-dup-mariadb.jsontests/fixtures/generic/ini-double-quote.ini 与 tests/fixtures/generic/ini-dup-double-quote.jsontests/fixtures/generic/ini-single-quote.ini 与 tests/fixtures/generic/ini-dup-single-quote.json赞分享开发工具【免费下载链接】jcCLI tool and python library that converts the output of popular command-line tools, file-types, and common strings to JSON, YAML, or Dictionaries. This allows piping of output to tools like jq and simplifying automation scripts.项目地址https://gitcode.com/gh_mirrors/jc/jc点击查看免费下载相关推荐jc 的 kv_dup 解析器详解把含重复键的 Key/Value 文件安全转成 JSON 列表jc 的 kv_dup 解析器详解把含重复键的 Key/Value 文件安全转成 JSON 列表 本文围绕 jc 项目中的 kv_dup Key/Value开发工具零样本立体匹配与深度估计实践FoundationStereo 让 AI 直接看懂三维场景零样本立体匹配与深度估计实践FoundationStereo 让 AI 直接看懂三维场景 FoundationStereo 是 NVIDIA 开源、获 CVPfastfetch 内置的 Shell 补全脚本怎么用为 bash/zsh/fish 启用 tab 补全fastfetch 内置的 Shell 补全脚本怎么用为 bash/zsh/fish 启用 tab 补全 fastfetch 仓库自带三份 shell 补全脚开发工具上一篇太吾绘卷游戏Mod项目常见问题解决方案下一篇【亲测免费】 UndertaleModTool 常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考