在 Python 与 Markdown 中嵌入 GraphQLvscode-graphql-syntax 的 inline.graphql.python 语法高亮全解析【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql本篇文章以 GraphQL 官方语法高亮扩展 vscode-graphql-syntax位于本仓库packages/vscode-graphql-syntax的 Python 嵌入语法为对象结合测试夹具tests/__fixtures__/test-py.md中列举的 7 种 GraphQL 嵌入书写模式深入讲解该扩展如何在 Python 源码与 Markdown 代码块中识别并高亮 GraphQL 查询包括 TextMate 注入语法的正则实现、token 作用域设计与快照测试验证流程。读完本文你将掌握在 Python 项目中正确书写可被高亮识别的 GraphQL 查询的多种姿势并理解其底层注入机制与测试方法。一、背景为什么需要 Python 嵌入语法GraphQL 查询通常以字符串形式嵌入在宿主语言中。在 Python 生态里常见的做法是把 GraphQL 文档写成字符串并交给gql(...)一类的函数处理如解析为 AST 或绑定 Schema或者直接在字符串头部加#graphql标记。但字符串内部对编辑器而言默认只是纯文本查询的关键字、字段、选择集完全没有高亮阅读与排错都很困难。vscode-graphql-syntax 扩展正是为了解决这个问题它提供一组注入型injectionTextMate 语法把完整的 GraphQL 语法source.graphql注入到 JS/TS、Vue、Markdown、Python、PHP、Scala、Reason/OCaml/ReScript 等宿主语言内部使嵌入的 GraphQL 文本获得与.graphql文件一致的着色。扩展的package.json描述中明确列出了对 Python 的支持。而tests/__fixtures__/test-py.md就是这套 Python 嵌入语法的核心测试夹具它是一份 Markdown 文件内部用python代码围栏包裹了全部 7 种典型嵌入写法。与之对应仓库还提供了同内容的纯 Python 文件 test.py二者被同一个语法inline.graphql.python覆盖——这正对应了该语法在injectTo中同时注入source.python与 Markdown 文本作用域的设计。二、7 种 Python 内嵌 GraphQL 的书写模式夹具全解夹具 test-py.md 以 Markdown Python 代码块形式逐一展示了被支持的嵌入写法。全部模式围绕同一段示例查询展开query getContinents { continents { code name } }模式 1gql()包裹三双引号字符串query gql( query getContinents { continents { code name } } )模式 2gql()包裹三单引号字符串query gql( query getContinents { continents { code name } } )模式 3gql()调用换行后接三单引号query gql( query getContinents { continents { code name } } )这种写法中开括号(与三引号不在同一行语法规则需要单独处理跨行场景。模式 4三单引号字符串 #graphql标记不绑定变量#graphql query getContinents { continents { code name } } 模式 5三单引号 #graphql标记的单行形式query #graphql query getContinents { continents { code name } }模式 6三双引号字符串 #graphql标记#graphql query getContinents { continents { code name } } 模式 7三双引号 #graphql标记的单行形式#graphql query getContinents { continents { code name } }归纳可见这 7 种模式覆盖了 4 类典型写法类别写法示例触发方式gql(...)单行包裹gql(...)/gql(...)识别gql(与三引号同行gql(...)跨行包裹gql(换行后接三引号识别gql(后无内容即换行三引号 #graphql标记#graphql .../#graphql ...识别引号后紧跟#graphql三引号 标记单行#graphql query {...}起始标记与查询同行三、底层实现inline.graphql.python语法规则逐条拆解实现位于 grammars/graphql.python.json声明为注入语法scopeName: inline.graphql.python, injectionSelector: L:(meta.embedded.block.python | source.python -string -comment)injectionSelector指明该语法注入到 Markdown 的 Python 代码块meta.embedded.block.python以及非字符串、非注释的普通 Python 源码source.python -string -comment前缀L:表示在行首位置注入。语法内包含 5 条 pattern与上文 4 类模式一一对应。pattern 1gql( 三单引号同行{ begin: \\s(gql)\\s*\\(\\s*(), contentName: meta.embedded.block.graphql, end: () }begin正则要求gql前有空白、gql后紧跟(且与三单引号在同一行beginCaptures把gql着色为entity.name.function把开引号着色为string.quoted.multi.python进入后整个区域获得contentName: meta.embedded.block.graphql区域内部include: source.graphql即复用完整的 GraphQL 语法进行着色end匹配收尾的三单引号并同样着色为 Python 多行字符串。pattern 2gql( 三双引号同行与 pattern 1 结构完全一致仅把三单引号换成三双引号graphql.python.json第 28-50 行覆盖模式 1。pattern 3gql(后跨行接三引号这是最复杂的规则第 51-100 行外层begin为\s(gql)\s*\(\s*$——匹配gql(出现在行尾、本行再无内容的情况end为\)|,。外层内部再定义两条子规则{ begin: ^\\s*(), end: () }, { begin: ^\\s*(\\\), end: (\\\) }即要求下一行以行首空白加三引号开头^\s*由此匹配模式 3 的跨行写法。pattern 4 与 5#graphql标记单/双引号{ begin: ()(#graphql), end: () }, { begin: (\\\)(#graphql), end: (\\\) }这两条第 101-144 行不要求gql(...)包裹只要三引号后紧跟#graphql标记即触发嵌入。注意开引号/被着色为string.quoted.multi.python#graphql本身被着色为comment.line.graphql.js作用域名沿用自 JS 注入语法中的注释命名可从快照确认标记之后的查询正文同样include: source.graphql因此query {...}写在与#graphql同一行模式 5、7也能被完整解析。四、包级注册scope 注入与 embeddedLanguages单有语法文件还不够扩展还需要在 package.json 的contributes.grammars中声明注入目标{ injectTo: [ source.python, text.html.markdown, text.html.derivative ], scopeName: inline.graphql.python, path: ./grammars/graphql.python.json, embeddedLanguages: { meta.embedded.block.graphql: graphql } }三个关键点的作用injectTo声明该语法要注入的宿主作用域——source.pythonPython 源码、text.html.markdown与text.html.derivativeMarkdown 及衍生文本因此python代码块同样生效。这也解释了为何同一个夹具同时存在 Markdown 版test-py.md与纯 Python 版test.pyembeddedLanguages把meta.embedded.block.graphql区域映射为graphql语言使编辑器对嵌入区域应用 GraphQL 的括号匹配、注释等语言配置scopeName作为测试与主题引用的唯一标识测试代码中即以inline.graphql.python为 scope 加载语法。五、测试与快照验证token 级证明高亮确实生效测试用例python-grammar.spec.ts 是该语法的 Vitest 测试import { tokenizeFile } from ./__utilities__/utilities; describe(inline.graphql.python grammar, () { const scope inline.graphql.python; it(should tokenize a simple python file, async () { const result await tokenizeFile(__fixtures__/test.py, scope); expect(result).toMatchSnapshot(); }); });tokenize 管线测试工具 utilities.ts 演示了 TextMate 语法测试的通用做法读取test.py后逐行调用grammar.tokenizeLine(line, ruleStack)并使用vscode-oniguruma提供正则引擎、vscode-textmate加载语法与注入关系最终把每段文本及其作用域列表与快照比对。快照揭示了哪些 token 作用域快照 python-grammar.spec.ts.snap 按行记录了每种模式的着色结果几个典型片段gql→entity.name.function三条gql(规则一致/开收引号 →string.quoted.multi.python在gql(包裹场景下还会叠加meta.embedded.block.graphql前缀#graphql→comment.line.graphql.js查询正文进入source.graphql后query→keyword.operation.graphql、操作名getContinents→entity.name.function.graphql、字段continents/code/name→variable.graphql、花括号 →punctuation.operation.graphql并依据嵌套深度叠加meta.selectionset.graphql。从快照还能观察到一个实现细节模式 2gql(...)中三单引号的作用域为string.quoted.multi.python而模式 1gql(...)中三双引号的作用域为meta.embedded.block.graphql string.quoted.multi.python——两者前缀不同这是 pattern 1/2 与 pattern 3 子规则在 capture 归属上的差异不影响查询正文的高亮一致性。如何运行测试扩展在package.json中声明了test: vitest run。在仓库根目录安装依赖后可以进入packages/vscode-graphql-syntax目录执行对应测试命令测试失败时会给出 token 与快照的差异便于在新增/调整嵌入模式时回归验证。六、使用与注意事项使用方式在 VS Code 扩展市场安装该扩展对应本仓库packages/vscode-graphql-syntax详见其 README.md后无需任何配置上述 7 种 Python 内嵌写法与 Markdownpython代码块中的 GraphQL 查询即可自动获得高亮.gql/.graphql/.graphqls文件则使用独立的source.graphql语法。命名偏好官方推荐在现代代码中使用#graphql标记写法模式 4-7它不依赖gql(...)函数名语义更清晰。能力边界需要说明的是本扩展只提供基于 TextMate 正则的词法着色tokenization不做语义分析、补全、校验等 LSP 功能——那些能力由本仓库中graphql-language-service-server、vscode-graphql等其他包承担可查阅 packages/vscode-graphql 目录了解。七、小结test-py.md虽是一份测试夹具却精确刻画了 Python 生态中嵌入 GraphQL 的全部典型写法。透过它可以看到 vscode-graphql-syntax 的一套完整工程实践以injectTo声明注入宿主、以contentNameinclude: source.graphql复用主语法、以正则 begin/end 界定嵌入边界再用 Vitest 快照把每种写法的 token 作用域固定下来。理解这套机制后无论你在 Python 代码还是 Markdown 文档中书写 GraphQL都能写出可被编辑器正确识别与高亮的代码也能为其他宿主语言移植类似的嵌入语法提供参考。相关文件索引夹具test-py.md、test.py语法规则graphql.python.json包注册package.json测试与快照python-grammar.spec.ts、python-grammar.spec.ts.snap测试工具utilities.ts【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Python 与 Markdown 中嵌入 GraphQL：vscode-graphql-syntax 的 inline.graphql.python 语法高亮全解析
在 Python 与 Markdown 中嵌入 GraphQLvscode-graphql-syntax 的 inline.graphql.python 语法高亮全解析【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql本篇文章以 GraphQL 官方语法高亮扩展 vscode-graphql-syntax位于本仓库packages/vscode-graphql-syntax的 Python 嵌入语法为对象结合测试夹具tests/__fixtures__/test-py.md中列举的 7 种 GraphQL 嵌入书写模式深入讲解该扩展如何在 Python 源码与 Markdown 代码块中识别并高亮 GraphQL 查询包括 TextMate 注入语法的正则实现、token 作用域设计与快照测试验证流程。读完本文你将掌握在 Python 项目中正确书写可被高亮识别的 GraphQL 查询的多种姿势并理解其底层注入机制与测试方法。一、背景为什么需要 Python 嵌入语法GraphQL 查询通常以字符串形式嵌入在宿主语言中。在 Python 生态里常见的做法是把 GraphQL 文档写成字符串并交给gql(...)一类的函数处理如解析为 AST 或绑定 Schema或者直接在字符串头部加#graphql标记。但字符串内部对编辑器而言默认只是纯文本查询的关键字、字段、选择集完全没有高亮阅读与排错都很困难。vscode-graphql-syntax 扩展正是为了解决这个问题它提供一组注入型injectionTextMate 语法把完整的 GraphQL 语法source.graphql注入到 JS/TS、Vue、Markdown、Python、PHP、Scala、Reason/OCaml/ReScript 等宿主语言内部使嵌入的 GraphQL 文本获得与.graphql文件一致的着色。扩展的package.json描述中明确列出了对 Python 的支持。而tests/__fixtures__/test-py.md就是这套 Python 嵌入语法的核心测试夹具它是一份 Markdown 文件内部用python代码围栏包裹了全部 7 种典型嵌入写法。与之对应仓库还提供了同内容的纯 Python 文件 test.py二者被同一个语法inline.graphql.python覆盖——这正对应了该语法在injectTo中同时注入source.python与 Markdown 文本作用域的设计。二、7 种 Python 内嵌 GraphQL 的书写模式夹具全解夹具 test-py.md 以 Markdown Python 代码块形式逐一展示了被支持的嵌入写法。全部模式围绕同一段示例查询展开query getContinents { continents { code name } }模式 1gql()包裹三双引号字符串query gql( query getContinents { continents { code name } } )模式 2gql()包裹三单引号字符串query gql( query getContinents { continents { code name } } )模式 3gql()调用换行后接三单引号query gql( query getContinents { continents { code name } } )这种写法中开括号(与三引号不在同一行语法规则需要单独处理跨行场景。模式 4三单引号字符串 #graphql标记不绑定变量#graphql query getContinents { continents { code name } } 模式 5三单引号 #graphql标记的单行形式query #graphql query getContinents { continents { code name } }模式 6三双引号字符串 #graphql标记#graphql query getContinents { continents { code name } } 模式 7三双引号 #graphql标记的单行形式#graphql query getContinents { continents { code name } }归纳可见这 7 种模式覆盖了 4 类典型写法类别写法示例触发方式gql(...)单行包裹gql(...)/gql(...)识别gql(与三引号同行gql(...)跨行包裹gql(换行后接三引号识别gql(后无内容即换行三引号 #graphql标记#graphql .../#graphql ...识别引号后紧跟#graphql三引号 标记单行#graphql query {...}起始标记与查询同行三、底层实现inline.graphql.python语法规则逐条拆解实现位于 grammars/graphql.python.json声明为注入语法scopeName: inline.graphql.python, injectionSelector: L:(meta.embedded.block.python | source.python -string -comment)injectionSelector指明该语法注入到 Markdown 的 Python 代码块meta.embedded.block.python以及非字符串、非注释的普通 Python 源码source.python -string -comment前缀L:表示在行首位置注入。语法内包含 5 条 pattern与上文 4 类模式一一对应。pattern 1gql( 三单引号同行{ begin: \\s(gql)\\s*\\(\\s*(), contentName: meta.embedded.block.graphql, end: () }begin正则要求gql前有空白、gql后紧跟(且与三单引号在同一行beginCaptures把gql着色为entity.name.function把开引号着色为string.quoted.multi.python进入后整个区域获得contentName: meta.embedded.block.graphql区域内部include: source.graphql即复用完整的 GraphQL 语法进行着色end匹配收尾的三单引号并同样着色为 Python 多行字符串。pattern 2gql( 三双引号同行与 pattern 1 结构完全一致仅把三单引号换成三双引号graphql.python.json第 28-50 行覆盖模式 1。pattern 3gql(后跨行接三引号这是最复杂的规则第 51-100 行外层begin为\s(gql)\s*\(\s*$——匹配gql(出现在行尾、本行再无内容的情况end为\)|,。外层内部再定义两条子规则{ begin: ^\\s*(), end: () }, { begin: ^\\s*(\\\), end: (\\\) }即要求下一行以行首空白加三引号开头^\s*由此匹配模式 3 的跨行写法。pattern 4 与 5#graphql标记单/双引号{ begin: ()(#graphql), end: () }, { begin: (\\\)(#graphql), end: (\\\) }这两条第 101-144 行不要求gql(...)包裹只要三引号后紧跟#graphql标记即触发嵌入。注意开引号/被着色为string.quoted.multi.python#graphql本身被着色为comment.line.graphql.js作用域名沿用自 JS 注入语法中的注释命名可从快照确认标记之后的查询正文同样include: source.graphql因此query {...}写在与#graphql同一行模式 5、7也能被完整解析。四、包级注册scope 注入与 embeddedLanguages单有语法文件还不够扩展还需要在 package.json 的contributes.grammars中声明注入目标{ injectTo: [ source.python, text.html.markdown, text.html.derivative ], scopeName: inline.graphql.python, path: ./grammars/graphql.python.json, embeddedLanguages: { meta.embedded.block.graphql: graphql } }三个关键点的作用injectTo声明该语法要注入的宿主作用域——source.pythonPython 源码、text.html.markdown与text.html.derivativeMarkdown 及衍生文本因此python代码块同样生效。这也解释了为何同一个夹具同时存在 Markdown 版test-py.md与纯 Python 版test.pyembeddedLanguages把meta.embedded.block.graphql区域映射为graphql语言使编辑器对嵌入区域应用 GraphQL 的括号匹配、注释等语言配置scopeName作为测试与主题引用的唯一标识测试代码中即以inline.graphql.python为 scope 加载语法。五、测试与快照验证token 级证明高亮确实生效测试用例python-grammar.spec.ts 是该语法的 Vitest 测试import { tokenizeFile } from ./__utilities__/utilities; describe(inline.graphql.python grammar, () { const scope inline.graphql.python; it(should tokenize a simple python file, async () { const result await tokenizeFile(__fixtures__/test.py, scope); expect(result).toMatchSnapshot(); }); });tokenize 管线测试工具 utilities.ts 演示了 TextMate 语法测试的通用做法读取test.py后逐行调用grammar.tokenizeLine(line, ruleStack)并使用vscode-oniguruma提供正则引擎、vscode-textmate加载语法与注入关系最终把每段文本及其作用域列表与快照比对。快照揭示了哪些 token 作用域快照 python-grammar.spec.ts.snap 按行记录了每种模式的着色结果几个典型片段gql→entity.name.function三条gql(规则一致/开收引号 →string.quoted.multi.python在gql(包裹场景下还会叠加meta.embedded.block.graphql前缀#graphql→comment.line.graphql.js查询正文进入source.graphql后query→keyword.operation.graphql、操作名getContinents→entity.name.function.graphql、字段continents/code/name→variable.graphql、花括号 →punctuation.operation.graphql并依据嵌套深度叠加meta.selectionset.graphql。从快照还能观察到一个实现细节模式 2gql(...)中三单引号的作用域为string.quoted.multi.python而模式 1gql(...)中三双引号的作用域为meta.embedded.block.graphql string.quoted.multi.python——两者前缀不同这是 pattern 1/2 与 pattern 3 子规则在 capture 归属上的差异不影响查询正文的高亮一致性。如何运行测试扩展在package.json中声明了test: vitest run。在仓库根目录安装依赖后可以进入packages/vscode-graphql-syntax目录执行对应测试命令测试失败时会给出 token 与快照的差异便于在新增/调整嵌入模式时回归验证。六、使用与注意事项使用方式在 VS Code 扩展市场安装该扩展对应本仓库packages/vscode-graphql-syntax详见其 README.md后无需任何配置上述 7 种 Python 内嵌写法与 Markdownpython代码块中的 GraphQL 查询即可自动获得高亮.gql/.graphql/.graphqls文件则使用独立的source.graphql语法。命名偏好官方推荐在现代代码中使用#graphql标记写法模式 4-7它不依赖gql(...)函数名语义更清晰。能力边界需要说明的是本扩展只提供基于 TextMate 正则的词法着色tokenization不做语义分析、补全、校验等 LSP 功能——那些能力由本仓库中graphql-language-service-server、vscode-graphql等其他包承担可查阅 packages/vscode-graphql 目录了解。七、小结test-py.md虽是一份测试夹具却精确刻画了 Python 生态中嵌入 GraphQL 的全部典型写法。透过它可以看到 vscode-graphql-syntax 的一套完整工程实践以injectTo声明注入宿主、以contentNameinclude: source.graphql复用主语法、以正则 begin/end 界定嵌入边界再用 Vitest 快照把每种写法的 token 作用域固定下来。理解这套机制后无论你在 Python 代码还是 Markdown 文档中书写 GraphQL都能写出可被编辑器正确识别与高亮的代码也能为其他宿主语言移植类似的嵌入语法提供参考。相关文件索引夹具test-py.md、test.py语法规则graphql.python.json包注册package.json测试与快照python-grammar.spec.ts、python-grammar.spec.ts.snap测试工具utilities.ts【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考