https://mac-vo.github.io/wiki/assets/js/ed9dbb2a.56ade119.js

1"use strict";(self.webpackChunksrc=self.webpackChunksrc||[]).push([[16],{3672:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>l,contentTitle:()=>c,default:()=>h,frontMatter:()=>o,metadata:()=>a,toc:()=>r});var t=i(6070),s=i(5337);const o={description:"Syntax of Config Files"},c="Config Syntax",a={id:"Config/Config-Spec",title:"Config Syntax",description:"Syntax of Config Files",source:"@site/docs/01-Config/00-Config-Spec.md",sourceDirName:"01-Config",slug:"/Config/Config-Spec",permalink:"/wiki/Config/Config-Spec",draft:!1,unlisted:!1,tags:[],version:"current",sidebarPosition:0,frontMatter:{description:"Syntax of Config Files"},sidebar:"tutorialSidebar",previous:{title:"Introduction",permalink:"/wiki/"},next:{title:"Overview",permalink:"/wiki/Modules/Modules"}},l={},r=[{value:"YAML Tags",id:"yaml-tags",level:2},{value:"Utility Functions",id:"utility-functions",level:2},{value:"<code>load_config(path: Path)</code>",id:"load_configpath-path",level:3},{value:"<code>build_dynamic_config(spec: DynamicConfigSpec)</code>",id:"build_dynamic_configspec-dynamicconfigspec",level:3},{value:"<code>asNamespace(dictionary)</code>",id:"asnamespacedictionary",level:3},{value:"<code>namespace_to_cfgnode(ns: SimpleNamespace)</code>",id:"namespace_to_cfgnodens-simplenamespace",level:3},{value:"Type Definitions",id:"type-definitions",level:2},{value:"Error Handling",id:"error-handling",level:2}];function d(e){const n={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",ul:"ul",...(0,s.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.header,{children:(0,t.jsx)(n.h1,{id:"config-syntax",children:"Config Syntax"})}),"\n",(0,t.jsxs)(n.p,{children:["We use the ",(0,t.jsx)(n.code,{children:"yaml"})," file format for configuration with some enhancements through custom tags and utility functions."]}),"\n",(0,t.jsx)(n.h2,{id:"yaml-tags",children:"YAML Tags"}),"\n",(0,t.jsx)(n.p,{children:"The following custom YAML tags are supported:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"!include <PATH>.yaml"})," - Reads and includes the content of another YAML file at the position of the tag. When using relative paths, they are resolved relative to the directory of the YAML file being loaded."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"!flatten_seq"})," - Flattens a nested sequence into a single-level sequence."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",metastring:'title="Example.yaml"',children:"arrays: !flatten_seq\r\n    - - a\r\n      - b\r\n    - c\n"})}),"\n",(0,t.jsx)(n.p,{children:"Will be translated to:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",metastring:'title="Actually_Loaded.yaml"',children:"arrays:\r\n    - a\r\n    - b\r\n    - c\n"})}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"utility-functions",children:"Utility Functions"}),"\n",(0,t.jsx)(n.p,{children:"The configuration system provides several utility functions:"}),"\n",(0,t.jsx)(n.h3,{id:"load_configpath-path",children:(0,t.jsx)(n.code,{children:"load_config(path: Path)"})}),"\n",(0,t.jsx)(n.p,{children:"Loads a YAML configuration file and returns it as both a SimpleNamespace object and a dictionary."}),"\n",(0,t.jsx)(n.h3,{id:"build_dynamic_configspec-dynamicconfigspec",children:(0,t.jsx)(n.code,{children:"build_dynamic_config(spec: DynamicConfigSpec)"})}),"\n",(0,t.jsx)(n.p,{children:"Builds a configuration from a dynamic specification that can include:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Dictionary configurations"}),"\n",(0,t.jsx)(n.li,{children:"List configurations"}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"LoadFrom"})," objects that specify paths to load YAML files"]}),"\n",(0,t.jsx)(n.li,{children:"Primitive types (str, int, float, bool)"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"asnamespacedictionary",children:(0,t.jsx)(n.code,{children:"asNamespace(dictionary)"})}),"\n",(0,t.jsx)(n.p,{children:"Converts a dictionary into a SimpleNamespace object, with nested dictionaries also being converted to SimpleNamespace objects. Null values are converted to empty SimpleNamespace objects."}),"\n",(0,t.jsx)(n.h3,{id:"namespace_to_cfgnodens-simplenamespace",children:(0,t.jsx)(n.code,{children:"namespace_to_cfgnode(ns: SimpleNamespace)"})}),"\n",(0,t.jsx)(n.p,{children:"Converts a SimpleNamespace configuration to a YACS CfgNode format, which is used by some components like Flowformer."}),"\n",(0,t.jsx)(n.h2,{id:"type-definitions",children:"Type Definitions"}),"\n",(0,t.jsx)(n.p,{children:"The configuration system uses the following type definitions:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-python",children:'DynamicConfigSpec = dict[str, "DynamicConfigSpec"] | list["DynamicConfigSpec"] | LoadFrom | str | int | float | bool | None\n'})}),"\n",(0,t.jsx)(n.h2,{id:"error-handling",children:"Error Handling"}),"\n",(0,t.jsx)(n.p,{children:"The configuration system includes robust error handling:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Attempts to include non-existent files will raise a ValueError with a descriptive message"}),"\n",(0,t.jsx)(n.li,{children:"File existence is checked before loading"}),"\n",(0,t.jsx)(n.li,{children:"Type safety is enforced through type hints and runtime checks"}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},5337:(e,n,i)=>{i.d(n,{R:()=>c,x:()=>a});var t=i(758);const s={},o=t.createContext(s);function c(e){const n=t.useContext(o);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:c(e.components),t.createElement(o.Provider,{value:n},e.children)}}}]);