Brand

Brand()

Brand guidelines in a class.

A brand instance encapsulates the color, typography and logo preferences for a given brand, typically found in brand guidelines created by a company’s marketing department. brand_yml.Brand organizes this information in a common, fully-specified class instance that makes it easy to re-use for theming any artifact from websites to data visualizations.

Unified brand information following the Brand YAML specification. Read brand metadata from a YAML file, typically named _brand.yml, with brand_yml.Brand.from_yaml or from a YAML string with brand_yml.Brand.from_yaml_str. Or create a full brand instance directly via this class.

Methods

Name	Description
from_yaml	Read a Brand YAML file.
from_yaml_str	Create a Brand instance from a string of YAML.
model_dump_yaml	Serialize the Brand object to YAML.

from_yaml

Brand.from_yaml(path)

Read a Brand YAML file.

Reads a Brand YAML file or finds and reads a _brand.yml file and returns a validated :class:Brand object.

Parameters

path: str | Path: The path to the Brand YAML file or a directory where _brand.yml is expected to be found. Typically, you can pass __file__ from the calling script to find _brand.yml in the current directory or any of its parent directories.

Returns

Name	Type	Description
		A validated `brand_yml.Brand` object with all fields populated according to the Brand YAML file.

Raises

Name	Type	Description
	FileNotFoundError	Raises a `FileNotFoundError` if no brand configuration file is found within the given path. Raises `ValueError` or other validation errors from pydantic if the Brand YAML file is invalid.

Examples

from brand_yml import Brand

brand = Brand.from_yaml(__file__)
brand = Brand.from_yaml("path/to/_brand.yml")

from_yaml_str

Brand.from_yaml_str(text, path=None)

Create a Brand instance from a string of YAML.

Parameters

text: str: The text of the Brand YAML file.
path: str | Path | None = None: The optional path on disk for supporting files like logos and fonts.

Returns

Name	Type	Description
		A validated `brand_yml.Brand` object with all fields populated according to the Brand YAML text.

Raises

Name	Type	Description
	ValueError	Raises `ValueError` or other validation errors from pydantic if the Brand YAML file is invalid.

Examples

from brand_yml import Brand

brand = Brand.from_yaml_str("""
meta:
  name: Brand YAML
color:
  primary: "#ff0202"
typography:
  base: Open Sans
""")

brand.meta

BrandMeta(name=BrandMetaName(full='Brand YAML'))

brand.color.primary

'#ff0202'

model_dump_yaml

Brand.model_dump_yaml(stream=None, *, transform=None)

Serialize the Brand object to YAML.

Write the brand_yml.Brand instance to a string or to a file on disk.

Examples

from brand_yml import Brand

brand = Brand.from_yaml_str("""
meta:
  name: Brand YAML
color:
  palette:
    orange: "#ff9a02"
  primary: orange
typography:
  headings: Raleway
""")

print(brand.model_dump_yaml())

meta:
  name:
    full: Brand YAML
color:
  palette:
    orange: '#ff9a02'
  primary: '#ff9a02'
typography:
  fonts:
    - family: Raleway
  headings:
    family: Raleway

Parameters

stream: Any = None: Passed to stream parameter of ruamel.yaml.YAML.dump.
transform: Any = None: Passed to transform parameter of ruamel.yaml.YAML.dump.

Returns

Name	Type	Description
	Any	A string with the YAML representation of the `brand` if `stream` is `None`. Otherwise, the YAML representation is written to `stream`, typically a file. Note that the output YAML may not be 100% identical to the input `_brand.yml`. The output will contain the fully validated Brand instance where default or computed values may be included as well as any values resolved during validation, such as colors.