Brand

Brand(**data)

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.

Attributes

meta

BrandMeta | None

Key identity information, name of the company, links to brand guidelines, etc.

logo

BrandLogo | BrandLogoResource | None

Files or links to the brand’s logo at various sizes.

color

BrandColor | None

Named colors in the brand’s color palette and semantic colors (e.g., primary, secondary, success, warning).

typography

BrandTypography | None

Font definitions, font family, weight, style, color, and line height for key elements (e.g., base, headings, and monospace text).

defaults

dict[str, Any] | None

Additional context-specific settings beyond the basic brand colors and typography.

path

Path | None

The file path of the brand configuration. This attribute is excluded from serialization and representation.

Methods

Name Description
from_yaml Create a Brand instance from 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.
use_logo Extract a logo resource from a brand.

from_yaml

Brand.from_yaml(path=None)

Create a Brand instance from a Brand YAML file.

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

To find a project-specific _brand.yml file, pass path the project directory or __file__ (the path of the current Python script). brand_yml.Brand.from_yaml will look in that directory or any parent directory for a _brand.yml, brand/_brand.yml or _brand/_brand.yml file (or the same variants with a .yaml extension). Note that it starts the search in the directory passed in and moves upward to find the _brand.yml file; it does not search into subdirectories of the current directory.

Parameters

path: str | Path | None = None

The path to the brand.yml 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 or _brand.yaml in the current directory or any of its parent directories. Alternatively, if no path is specified, the BRAND_YML_PATH environment variable is checked for the path to the brand.yml file.

Returns

Name Type Description
A validated Brand object with all fields populated according to the brand.yml file.

Raises

Name Type Description
FileNotFoundError Raises a FileNotFoundError if no brand configuration file is found within the given path.
ValueError Raises ValueError or other validation errors from pydantic if the brand.yml 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.