Logos and Images

BrandLogo

BrandLogo()

Brand Logos

logo stores a single brand logo or a set of logos at three different size points and possibly in different color schemes. Store all of your brand’s logo or image assets in images with meaningful names. Logos can be mapped to three preset sizes – small, medium, and large – and each can be either a single logo file or a light/dark variant (brand_yml.BrandLightDark).

To attach alternative text to an image, provide the image as a dictionary including path (the image location) and alt (the short, alternative text describing the image).

Attributes

images

dict[str, BrandLogoResource] | None

A dictionary containing any number of logos or brand images. You can refer to these images by their key name in small, medium or large. Local file paths should be relative to the _brand.yml source file. Remote files are also permitted; please use a full URL to the image.

logo:
  images:
    white: pandas_white.svg
    white_online: "https://upload.wikimedia.org/wikipedia/commons/e/ed/Pandas_logo.svg"
  small: white

small

BrandLogoFileType | None

A small logo, typically used as an favicon or mobile app icon.

medium

BrandLogoFileType | None

A medium-sized logo, typically used in the header of a website.

large

BrandLogoFileType | None

A large logo, typically used in a larger format such as a title slide or in marketing materials.

Examples

_brand.yml

logo: posit.png

_brand.yml

logo:
  small: logos/pandas/pandas_mark.svg
  medium: logos/pandas/pandas_secondary.svg
  large: logos/pandas/pandas.svg

_brand.yml

logo:
  small: logos/pandas/pandas_mark.svg
  medium:
    light: logos/pandas/pandas_secondary.svg
    dark: logos/pandas/pandas_secondary_white.svg
  large: logos/pandas/pandas.svg

_brand.yml

logo:
  images:
    mark: logos/pandas/pandas_mark.svg
    mark-white: logos/pandas/pandas_mark_white.svg
    secondary: logos/pandas/pandas_secondary.svg
    secondary-white: logos/pandas/pandas_secondary_white.svg
    pandas: logos/pandas/pandas.svg
    pandas-white: logos/pandas/pandas_white.svg
  small: mark
  medium:
    light: logos/pandas/pandas_secondary.svg
    dark: secondary-white
  large: pandas

_brand.yml

logo:
  images:
    mark:
      path: logos/pandas/pandas_mark.svg
      alt: pandas logo with blue bars and yellow and pink dots
    mark-white: logos/pandas/pandas_mark_white.svg
    secondary: logos/pandas/pandas_secondary.svg
    secondary-white:
      path: logos/pandas/pandas_secondary_white.svg
      alt: pandas logo with bars and dots over the word "pandas"
    pandas: logos/pandas/pandas.svg
    pandas-white: logos/pandas/pandas_white.svg
  small: mark
  medium:
    light:
      path: logos/pandas/pandas_secondary.svg
      alt: pandas logo with bars and dots over the word "pandas"
    dark: secondary-white
  large:
    path: logos/pandas/pandas.svg
    alt: pandas bars and dots to the right of the word "pandas"

BrandLogoResource

BrandLogoResource()

A logo resource, a file with optional alternative text

Attributes

Name	Description
alt	Alterative text for the image, used for accessibility.
path	The path to the logo resource. This can be a local file or a URL.

BrandLightDark

BrandLightDark()

A Light/Dark Variant

Holds variants for light and dark settings. Generally speaking light settings have white or light backgrounds and dark foreground colors (black text on a white page) and dark settings use black or dark background with light foreground colors (white text on a black page).

Attributes

Name	Description
dark	Value in dark mode.
light	Value in light mode.

FileLocation

FileLocation()

The base class for a file location, either a local or an online file.

Local files are handled by brand_yml.file.FileLocationLocal and are always considered relative to the source _brand.yml file.

Online files are handled by brand_yml.file.FileLocationUrl and are a URL starting with https:// or http://. Absolute paths for local or network files are supported via FileLocationUrl when using the file:// prefix.

FileLocationLocal

FileLocationLocal()

A local file location.

When used in a brand_yml.Brand instance, this class carries both the relative path to the file, relative to the source _brand.yml, and the absolute path of the file on disk.

Methods

Name	Description
absolute	Absolute path of the file location, relative to the root directory.
exists	Check that the file exists at its absolute path.
relative	Relative path of the file location.
set_root_dir	Update the root directory of this file location.
validate_exists	Validate that the file exists at its absolute path.

absolute

FileLocationLocal.absolute()

Absolute path of the file location, relative to the root directory.

Returns the absolute path to the file, relative to the root directory, which is most typically the directory containing the _brand.yml file.

exists

FileLocationLocal.exists()

Check that the file exists at its absolute path.

relative

FileLocationLocal.relative()

Relative path of the file location.

Returns the relative path to the file as it would appear in the source _brand.yml file.

set_root_dir

FileLocationLocal.set_root_dir(root_dir)

Update the root directory of this file location.

In general, the root directory is the parent directory containing the source brand_yml file. If you relocate the file, this method can be used to update the new local file location.

validate_exists

FileLocationLocal.validate_exists()

Validate that the file exists at its absolute path.

Raises

Name	Type	Description
	FileNotFoundError	Raises a `FileNotFoundError` if the file does not exist at its absolute path location.

FileLocationUrl

FileLocationUrl()

A hosted, online file location, i.e. a URL.

A URL to a single file, typically an online file path starting with http:// or https://. This class can also be used for the absolute path of local or networked files, which should start with file:// (otherwise local files are handled by brand_yml.file.FileLocationLocal).

file.FileLocationLocalOrUrlType

file.FileLocationLocalOrUrlType

A type representing a file location that may be a local path or URL.