diagrams 项目Diagram核心对象完全指南从基础上下文到高级渲染选项【免费下载链接】diagrams:art: Diagram as Code for prototyping cloud system architectures项目地址: https://gitcode.com/GitHub_Trending/di/diagrams本文围绕开源项目 diagramsDiagram as Code中最核心的Diagram类展开它既是一张图的全局上下文global context也是控制文件命名、输出格式、自动展示与 Graphviz 自定义属性的唯一入口。读完本文你将掌握如何用几行 Python 在with块中声明并渲染出 PNG/JPG/SVG/PDF/dot 架构图如何在 Jupyter Notebook 中直接内联展示以及如何通过graph_attr、node_attr、edge_attr深度定制图形的外观细节。Diagram是什么Diagram是 diagrams 中代表一张图的首要对象。它同时承担两个职责上下文容器它以 Python 上下文管理器with的形式包裹节点与连线的声明过程所有在with Diagram(...)块内创建的节点、集群和边都会自动归属到当前这张图见 diagrams/init.py 中基于contextvars实现的__diagram/__cluster全局上下文。渲染执行器退出with块时自动调用 Graphviz 完成渲染并把生成出来的中间 dot 文件清理掉。Diagram构造函数的第一个参数name会同时用于生成输出文件名。例如把下面代码保存为diagram.pyfrom diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram): EC2(web)然后执行$ python diagram.py程序会在当前工作目录下生成一张仅含单个EC2节点的图片文件名为simple_diagram.png并立即自动打开这张图片。这里值得展开的是文件名的产生规则name只是图的名字会被用作 dot 图中label实际文件名会经过_.join(name.split()).lower()的清洗——Simple Diagram 先按空白分词再拼成Simple_Diagram并转小写最终得到simple_diagramdiagrams/init.py。这也是为什么图中节点名可以包含空格、而磁盘文件名总是规整的下划线小写形式。前置条件diagrams 需要 Python 3.9见 pyproject.toml并且本机必须已经安装 Graphvizdot命令需要位于PATH中否则渲染阶段会失败。安装步骤参见 docs/getting-started/installation.md。在 Jupyter Notebook 中直接渲染Diagram除生成图片文件外还实现了_repr_png_方法diagrams/init.py因此它可以被 Jupyter 的富文本输出机制识别直接在 Notebook 单元格中渲染成内联图片from diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram) as diag: EC2(web) diag关键点有两个将with Diagram(...) as diag:的上下文对象赋给变量diag在with块结束后于下一个单元格或同一单元格末尾输入diag触发其富文本展示。由于_repr_png_内部通过dot.pipe(formatpng)向 Graphviz 请求 PNG 字节流Jupyter 就能把图直接内联渲染出来非常适合在分析文档、方案评审时边写代码边看架构。核心参数输出格式、文件名与自动展示outformat指定输出格式默认输出格式是png。支持的值包括png、jpg、svg、pdf、dotfrom diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram, outformatjpg): EC2(web)outformat还支持传入一个列表一次调用同时产出多种格式典型用途是同时要位图用于文档插图和 dot用于二次编辑或 diff 审查from diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram Multi Output, outformat[jpg, png, dot]): EC2(web)从实现看格式校验在白名单上进行且不区分大小写Diagram.__outformats (png, jpg, svg, pdf, dot)渲染时会对列表中的每个格式逐个调用self.dot.render(formatone_format, ...)diagrams/init.py、diagrams/init.py。若传入白名单之外的格式会抛出ValueError这一点被 tests/test_diagram.py 中test_validate_outformat用pnp、jpe、unknown等非法值验证过。filename自定义输出文件名如果不希望文件名由name推断可以显式指定filename。不要包含扩展名扩展名由outformat决定from diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram, filenamemy_diagram): EC2(web)以上代码会生成my_diagram.png。结合源码可以看清三种命名的优先级diagrams/init.py场景实际文件名name与filename均为空固定回退为diagrams_image只给name如Simple Diagramsimple_diagram分词转小写下划线显式给出filename直接使用该值name仅作图的label最后一种兜底行为同样被测试覆盖tests/test_diagram.py 的test_empty_name验证了空名字时会生成diagrams_image.png而test_default_filename/test_custom_filenametests/test_diagram.py分别验证了由name推断与显式filename两种路径。show关闭渲染后自动打开图片默认showTrue图片渲染成功后会调用系统默认查看器自动打开。在 CI、批量生成或服务端场景下这显然不合适应显式关闭from diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram, showFalse): EC2(web)自定义 Graphviz 属性graph_attr/node_attr/edge_attrdiagrams 允许你为底层 Graphviz 图直接传入自定义的 dot 属性三类作用域均可覆盖graph_attr作用于整张图例如rankdir、bgcolor、fontsize、padnode_attr作用于全部节点例如shape、styleedge_attr作用于全部连线例如color、style。from diagrams import Diagram from diagrams.aws.compute import EC2 graph_attr { fontsize: 45, bgcolor: transparent } with Diagram(Simple Diagram, showFalse, graph_attrgraph_attr): EC2(web)当把bgcolor设为transparent时导出的 PNG 背景透明可直接叠加到文档或幻灯片底色上。graph_attr、node_attr、edge_attr传入的字典会被合并进各自的内置默认属性之上传入值覆盖默认值因此不必把每个属性都写全。为了帮你准确预估合并后的效果这里给出源码中的内置默认属性diagrams/init.py_default_graph_attrs { pad: 2.0, splines: ortho, nodesep: 0.60, ranksep: 0.75, fontname: Sans-Serif, fontsize: 15, fontcolor: #2D3436, } _default_node_attrs { shape: box, style: rounded, fixedsize: true, width: 1.4, height: 1.4, labelloc: b, imagescale: true, fontname: Sans-Serif, fontsize: 13, fontcolor: #2D3436, } _default_edge_attrs { color: #7B8894, }同时图名name会被自动写入label节点与集群的默认字体颜色与连线灰色形成项目统一的视觉风格。若你需要调整连线默认颜色、节点内边距等全局观感直接在这三个参数上做增量覆盖即可无需关心其余默认值。有关 Graphviz dot 属性取值表与语义可参考 pyproject.toml 声明的底层graphviz依赖版本区间内所对应的官方属性文档属性名与 dot 语法保持一致。文档未展开但同样属于Diagram的参数进入with之前Diagram还暴露了几个与布局、渲染语义直接相关的参数它们与上文的选项一样接受严格的校验方向支持TB / BT / LR / RL曲线风格仅支持ortho / curved见 diagrams/init.pyfrom diagrams import Diagram from diagrams.aws.compute import EC2 # direction: 数据流方向默认 LR即从左到右对应 dot 的 rankdir # curvestyle: 连线弯曲风格默认 ortho正交直角连线可选 curved # strict: 为 True 时 Graphviz 将合并重复边 # autolabel: 为 True 时自动为节点标注加上类名前缀如 EC2\nweb with Diagram(Simple Diagram, directionLR, curvestyleortho, strictFalse, autolabelFalse, showFalse): EC2(web)其中direction在 tests/test_diagram.py 中被验证合法值TB/BT/LR/RL/tb均能构造成功而BR/TL/Unknown会抛出ValueErrorcurvestyle同理tests/test_diagram.py。值得注意的是direction会被写入 dot 的rankdir而curvestyle会被写入splines——因此若你通过graph_attr覆盖了这两项二者会按先默认值、后用户覆盖值的顺序决定最终生效者。深入底层Diagram的生命周期与渲染原理理解Diagram的机制需要看懂它与 Node、Cluster 的协作方式。核心逻辑全部位于 diagrams/init.py全局上下文注入模块顶部用contextvars.ContextVar定义了__diagram与__cluster两个全局上下文diagrams/init.py。Diagram.__enter__把自身setdiagram(self)设置到上下文中diagrams/init.py此后任意Node或Cluster构造时都会调用getdiagram()来确认自己属于哪张图。节点的归属与接线Node.__init__若在Diagram上下文之外被创建会直接抛出EnvironmentErrordiagrams/init.py测试test_node_not_in_diagram专门断言了这一点tests/test_diagram.py。连线通过Node的运算符重载、、-最终汇聚到Diagram.connect为两个节点创建一条边diagrams/init.py。退出即渲染Diagram.__exit__调用self.render()随后用os.remove(self.filename)删除 Graphviz 生成的中间 dot 源文件只保留最终图片最后把全局上下文置空diagrams/init.py。所以你在工作目录里只会看到成品的xxx.png/xxx.jpg等文件除非outformat中显式包含了dot。这种进入赋值、退出渲染清理的上下文管理模式让节点、集群见 docs/guides/cluster.md、连线和边样式见 docs/guides/edge.md无需层层传递引用代码结构天然清晰每一层with块即一张局部作用域缩进即所属关系。常见的组合用法与注意事项把上面各参数组合起来一个典型的交付给 CI 流水线的写法如下from diagrams import Diagram from diagrams.aws.compute import EC2 from diagrams.aws.database import RDS from diagrams.aws.network import ELB with Diagram(Web Service, filenamearch/web_service, outformat[png, svg], showFalse, graph_attr{bgcolor: transparent, fontsize: 45}): ELB(lb) EC2(web) RDS(userdb)实践中有几点需要留意文件名不含扩展名无论单个格式还是格式列表filename永远只写主干名扩展名交给outformat多格式渲染时各文件共享同一主干名。先画后改的迭代方式开发阶段用showTrue让每次运行自动弹图进入批量生成或提交 CI 前改为showFalse避免阻塞式弹窗干扰流程。dot格式的价值outformat[dot]会保留可读的 Graphviz 源码文件便于人工 code review 架构变更、或交给其他工具二次处理。透明背景的适用性bgcolor: transparent仅在输出 PNG/SVG 时有意义若输出 JPG透明概念不成立应改为具体色值。非法参数会尽早失败格式、方向、曲线风格三类参数均在构造期校验ValueError而不是渲染期才报错所以写错就快速暴露是Diagram的默认行为。Diagram是 diagrams 一切能力的承载点向外决定产物的格式与文件名向内提供节点、集群与连线的统一上下文。掌握了本文介绍的参数体系与生命周期再配合 docs/getting-started/examples.md 中的成品示例就可以开始用纯代码产出专业级的云架构图了。【免费下载链接】diagrams:art: Diagram as Code for prototyping cloud system architectures项目地址: https://gitcode.com/GitHub_Trending/di/diagrams创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 diagrams 项目 `Diagram` 核心对象完全指南：从基础上下文到高级渲染选项
diagrams 项目Diagram核心对象完全指南从基础上下文到高级渲染选项【免费下载链接】diagrams:art: Diagram as Code for prototyping cloud system architectures项目地址: https://gitcode.com/GitHub_Trending/di/diagrams本文围绕开源项目 diagramsDiagram as Code中最核心的Diagram类展开它既是一张图的全局上下文global context也是控制文件命名、输出格式、自动展示与 Graphviz 自定义属性的唯一入口。读完本文你将掌握如何用几行 Python 在with块中声明并渲染出 PNG/JPG/SVG/PDF/dot 架构图如何在 Jupyter Notebook 中直接内联展示以及如何通过graph_attr、node_attr、edge_attr深度定制图形的外观细节。Diagram是什么Diagram是 diagrams 中代表一张图的首要对象。它同时承担两个职责上下文容器它以 Python 上下文管理器with的形式包裹节点与连线的声明过程所有在with Diagram(...)块内创建的节点、集群和边都会自动归属到当前这张图见 diagrams/init.py 中基于contextvars实现的__diagram/__cluster全局上下文。渲染执行器退出with块时自动调用 Graphviz 完成渲染并把生成出来的中间 dot 文件清理掉。Diagram构造函数的第一个参数name会同时用于生成输出文件名。例如把下面代码保存为diagram.pyfrom diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram): EC2(web)然后执行$ python diagram.py程序会在当前工作目录下生成一张仅含单个EC2节点的图片文件名为simple_diagram.png并立即自动打开这张图片。这里值得展开的是文件名的产生规则name只是图的名字会被用作 dot 图中label实际文件名会经过_.join(name.split()).lower()的清洗——Simple Diagram 先按空白分词再拼成Simple_Diagram并转小写最终得到simple_diagramdiagrams/init.py。这也是为什么图中节点名可以包含空格、而磁盘文件名总是规整的下划线小写形式。前置条件diagrams 需要 Python 3.9见 pyproject.toml并且本机必须已经安装 Graphvizdot命令需要位于PATH中否则渲染阶段会失败。安装步骤参见 docs/getting-started/installation.md。在 Jupyter Notebook 中直接渲染Diagram除生成图片文件外还实现了_repr_png_方法diagrams/init.py因此它可以被 Jupyter 的富文本输出机制识别直接在 Notebook 单元格中渲染成内联图片from diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram) as diag: EC2(web) diag关键点有两个将with Diagram(...) as diag:的上下文对象赋给变量diag在with块结束后于下一个单元格或同一单元格末尾输入diag触发其富文本展示。由于_repr_png_内部通过dot.pipe(formatpng)向 Graphviz 请求 PNG 字节流Jupyter 就能把图直接内联渲染出来非常适合在分析文档、方案评审时边写代码边看架构。核心参数输出格式、文件名与自动展示outformat指定输出格式默认输出格式是png。支持的值包括png、jpg、svg、pdf、dotfrom diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram, outformatjpg): EC2(web)outformat还支持传入一个列表一次调用同时产出多种格式典型用途是同时要位图用于文档插图和 dot用于二次编辑或 diff 审查from diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram Multi Output, outformat[jpg, png, dot]): EC2(web)从实现看格式校验在白名单上进行且不区分大小写Diagram.__outformats (png, jpg, svg, pdf, dot)渲染时会对列表中的每个格式逐个调用self.dot.render(formatone_format, ...)diagrams/init.py、diagrams/init.py。若传入白名单之外的格式会抛出ValueError这一点被 tests/test_diagram.py 中test_validate_outformat用pnp、jpe、unknown等非法值验证过。filename自定义输出文件名如果不希望文件名由name推断可以显式指定filename。不要包含扩展名扩展名由outformat决定from diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram, filenamemy_diagram): EC2(web)以上代码会生成my_diagram.png。结合源码可以看清三种命名的优先级diagrams/init.py场景实际文件名name与filename均为空固定回退为diagrams_image只给name如Simple Diagramsimple_diagram分词转小写下划线显式给出filename直接使用该值name仅作图的label最后一种兜底行为同样被测试覆盖tests/test_diagram.py 的test_empty_name验证了空名字时会生成diagrams_image.png而test_default_filename/test_custom_filenametests/test_diagram.py分别验证了由name推断与显式filename两种路径。show关闭渲染后自动打开图片默认showTrue图片渲染成功后会调用系统默认查看器自动打开。在 CI、批量生成或服务端场景下这显然不合适应显式关闭from diagrams import Diagram from diagrams.aws.compute import EC2 with Diagram(Simple Diagram, showFalse): EC2(web)自定义 Graphviz 属性graph_attr/node_attr/edge_attrdiagrams 允许你为底层 Graphviz 图直接传入自定义的 dot 属性三类作用域均可覆盖graph_attr作用于整张图例如rankdir、bgcolor、fontsize、padnode_attr作用于全部节点例如shape、styleedge_attr作用于全部连线例如color、style。from diagrams import Diagram from diagrams.aws.compute import EC2 graph_attr { fontsize: 45, bgcolor: transparent } with Diagram(Simple Diagram, showFalse, graph_attrgraph_attr): EC2(web)当把bgcolor设为transparent时导出的 PNG 背景透明可直接叠加到文档或幻灯片底色上。graph_attr、node_attr、edge_attr传入的字典会被合并进各自的内置默认属性之上传入值覆盖默认值因此不必把每个属性都写全。为了帮你准确预估合并后的效果这里给出源码中的内置默认属性diagrams/init.py_default_graph_attrs { pad: 2.0, splines: ortho, nodesep: 0.60, ranksep: 0.75, fontname: Sans-Serif, fontsize: 15, fontcolor: #2D3436, } _default_node_attrs { shape: box, style: rounded, fixedsize: true, width: 1.4, height: 1.4, labelloc: b, imagescale: true, fontname: Sans-Serif, fontsize: 13, fontcolor: #2D3436, } _default_edge_attrs { color: #7B8894, }同时图名name会被自动写入label节点与集群的默认字体颜色与连线灰色形成项目统一的视觉风格。若你需要调整连线默认颜色、节点内边距等全局观感直接在这三个参数上做增量覆盖即可无需关心其余默认值。有关 Graphviz dot 属性取值表与语义可参考 pyproject.toml 声明的底层graphviz依赖版本区间内所对应的官方属性文档属性名与 dot 语法保持一致。文档未展开但同样属于Diagram的参数进入with之前Diagram还暴露了几个与布局、渲染语义直接相关的参数它们与上文的选项一样接受严格的校验方向支持TB / BT / LR / RL曲线风格仅支持ortho / curved见 diagrams/init.pyfrom diagrams import Diagram from diagrams.aws.compute import EC2 # direction: 数据流方向默认 LR即从左到右对应 dot 的 rankdir # curvestyle: 连线弯曲风格默认 ortho正交直角连线可选 curved # strict: 为 True 时 Graphviz 将合并重复边 # autolabel: 为 True 时自动为节点标注加上类名前缀如 EC2\nweb with Diagram(Simple Diagram, directionLR, curvestyleortho, strictFalse, autolabelFalse, showFalse): EC2(web)其中direction在 tests/test_diagram.py 中被验证合法值TB/BT/LR/RL/tb均能构造成功而BR/TL/Unknown会抛出ValueErrorcurvestyle同理tests/test_diagram.py。值得注意的是direction会被写入 dot 的rankdir而curvestyle会被写入splines——因此若你通过graph_attr覆盖了这两项二者会按先默认值、后用户覆盖值的顺序决定最终生效者。深入底层Diagram的生命周期与渲染原理理解Diagram的机制需要看懂它与 Node、Cluster 的协作方式。核心逻辑全部位于 diagrams/init.py全局上下文注入模块顶部用contextvars.ContextVar定义了__diagram与__cluster两个全局上下文diagrams/init.py。Diagram.__enter__把自身setdiagram(self)设置到上下文中diagrams/init.py此后任意Node或Cluster构造时都会调用getdiagram()来确认自己属于哪张图。节点的归属与接线Node.__init__若在Diagram上下文之外被创建会直接抛出EnvironmentErrordiagrams/init.py测试test_node_not_in_diagram专门断言了这一点tests/test_diagram.py。连线通过Node的运算符重载、、-最终汇聚到Diagram.connect为两个节点创建一条边diagrams/init.py。退出即渲染Diagram.__exit__调用self.render()随后用os.remove(self.filename)删除 Graphviz 生成的中间 dot 源文件只保留最终图片最后把全局上下文置空diagrams/init.py。所以你在工作目录里只会看到成品的xxx.png/xxx.jpg等文件除非outformat中显式包含了dot。这种进入赋值、退出渲染清理的上下文管理模式让节点、集群见 docs/guides/cluster.md、连线和边样式见 docs/guides/edge.md无需层层传递引用代码结构天然清晰每一层with块即一张局部作用域缩进即所属关系。常见的组合用法与注意事项把上面各参数组合起来一个典型的交付给 CI 流水线的写法如下from diagrams import Diagram from diagrams.aws.compute import EC2 from diagrams.aws.database import RDS from diagrams.aws.network import ELB with Diagram(Web Service, filenamearch/web_service, outformat[png, svg], showFalse, graph_attr{bgcolor: transparent, fontsize: 45}): ELB(lb) EC2(web) RDS(userdb)实践中有几点需要留意文件名不含扩展名无论单个格式还是格式列表filename永远只写主干名扩展名交给outformat多格式渲染时各文件共享同一主干名。先画后改的迭代方式开发阶段用showTrue让每次运行自动弹图进入批量生成或提交 CI 前改为showFalse避免阻塞式弹窗干扰流程。dot格式的价值outformat[dot]会保留可读的 Graphviz 源码文件便于人工 code review 架构变更、或交给其他工具二次处理。透明背景的适用性bgcolor: transparent仅在输出 PNG/SVG 时有意义若输出 JPG透明概念不成立应改为具体色值。非法参数会尽早失败格式、方向、曲线风格三类参数均在构造期校验ValueError而不是渲染期才报错所以写错就快速暴露是Diagram的默认行为。Diagram是 diagrams 一切能力的承载点向外决定产物的格式与文件名向内提供节点、集群与连线的统一上下文。掌握了本文介绍的参数体系与生命周期再配合 docs/getting-started/examples.md 中的成品示例就可以开始用纯代码产出专业级的云架构图了。【免费下载链接】diagrams:art: Diagram as Code for prototyping cloud system architectures项目地址: https://gitcode.com/GitHub_Trending/di/diagrams创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考