feat: brand_yaml Python package

.github/workflows/py-test.yml

@@ -0,0 +1,52 @@
+name: Test - Python
+
+on:
+  push:
+    branches: [main]
+    paths: 
+      - 'pkg-py/*'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/py-test.yml'
+  pull_request:
+    paths: 
+      - 'pkg-py/*'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/py-test.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 🚀 Install uv
+        uses: astral-sh/setup-uv@v2
+
+      - name: 🐍 Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: 📦 Install the project
+        run: uv sync --python ${{ matrix.python-version }} --no-dev --extra test
+
+      - name: 🧪 Check tests
+        run: make py-check-tests
+
+      - name: 📝 Check types
+        run: make py-check-types
+
+      - name: 📐 Check formatting
+        run: make py-check-format

.gitignore

@@ -0,0 +1,2 @@
+__pycache__
+.coverage

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+        "charliermarsh.ruff"
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.fixAll": "explicit",
+            "source.organizeImports": "explicit"
+        },
+        "editor.defaultFormatter": "charliermarsh.ruff"
+    }
+}

Makefile

@@ -0,0 +1,78 @@
+.PHONY: docs
+docs:  ## [docs] Build the documentation
+	quarto render docs
+
+.PHONY: docs-preview
+docs-preview:  ## [docs] Preview the documentation
+	quarto preview docs
+
+.PHONY: py-setup
+py-setup:  ## [py] Setup python environment
+	uv sync --all-extras
+
+.PHONY: py-check
+py-check:  py-check-tests py-check-format py-check-types ## [py] Run python checks
+
+.PHONY: py-check-tox
+py-check-tox:  ## [py] Run python 3.9 - 3.12 checks with tox
+	@echo ""
+	@echo "🔄 Running tests and type checking with tox for Python 3.9--3.12"
+	uv run tox run-parallel
+
+.PHONY: py-check-tests
+py-check-tests:  ## [py] Run python tests
+	@echo ""
+	@echo "🧪 Running tests with pytest"
+	uv run pytest
+
+.PHONY: py-check-types
+py-check-types:  ## [py] Run python type checks
+	@echo ""
+	@echo "📝 Checking types with pyright"
+	uv run pyright
+
+.PHONY: py-check-format
+py-check-format:
+	@echo ""
+	@echo "📐 Checking format with ruff"
+	uv run ruff check pkg-py --config pyproject.toml
+
+.PHONY: py-format
+py-format: ## [py] Format python code
+	uv run ruff check --fix pkg-py --config pyproject.toml
+	uv run ruff format pkg-py --config pyproject.toml
+
+.PHONY: py-coverage
+py-coverage: ## [py] Generate coverage report
+	@echo "📔 Generating coverage report"
+	uv run coverage run -m pytest
+	uv run coverage report
+
+.PHONY: py-coverage-report
+py-coverage-report: py-coverage ## [py] Generate coverage report and open it in browser
+	uv run coverage html
+	@echo ""
+	@echo "📡 Serving coverage report at http://localhost:8081/"
+	@npx http-server htmlcov --silent -p 8081
+
+.PHONY: py-update-snaps
+py-update-snaps:  ## [py] Update python test snapshots
+	@echo "📸 Updating pytest snapshots"
+	uv run pytest --snapshot-update
+
+.PHONY: help
+help:  ## Show help messages for make targets
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; { \
+		printf "\033[32m%-18s\033[0m", $$1; \
+		if ($$2 ~ /^\[docs\]/) { \
+			printf "\033[34m[docs]\033[0m%s\n", substr($$2, 7); \
+		} else if ($$2 ~ /^\[py\]/) { \
+			printf "  \033[33m[py]\033[0m%s\n", substr($$2, 5); \
+		} else if ($$2 ~ /^\[r\]/) { \
+			printf "   \033[31m[r]\033[0m%s\n", substr($$2, 4); \
+		} else { \
+			printf "       %s\n", $$2; \
+		} \
+	}'
+
+.DEFAULT_GOAL := help

examples/brand-color-direct-posit.yml

@@ -0,0 +1,12 @@
+color:
+  foreground: "#151515"
+  background: "#FFFFFF"
+  primary: "#447099"
+  secondary: "#707073"
+  tertiary: "#C2C2C4"
+  success: "#72994E"
+  info: "#419599"
+  warning: "#EE6331"
+  danger: "#9A4665"
+  light: "#FFFFFF"
+  dark: "#404041"

examples/brand-color-palette-internal.yml

@@ -0,0 +1,21 @@
+color:
+  palette:
+    white: "#FFFFFF"
+    black: "#151515"
+    blue: "#447099"
+    orange: "#EE6331"
+    green: "#72994E"
+    teal: "#419599"
+    burgundy: "#9A4665"
+
+  foreground: black
+  background: white
+  primary: blue
+  secondary: "#707073"
+  tertiary: "#C2C2C4"
+  success: green
+  info: primary
+  warning: orange
+  danger: burgundy
+  light: background
+  dark: "#404041"

examples/brand-color-palette-posit.yml

@@ -0,0 +1,21 @@
+color:
+  palette:
+    white: "#FFFFFF"
+    black: "#151515"
+    blue: "#447099"
+    orange: "#EE6331"
+    green: "#72994E"
+    teal: "#419599"
+    burgundy: "#9A4665"
+
+  foreground: black
+  background: white
+  primary: blue
+  secondary: "#707073"
+  tertiary: "#C2C2C4"
+  success: green
+  info: teal
+  warning: orange
+  danger: burgundy
+  light: white
+  dark: "#404041"

examples/brand-logo-full.yml

@@ -0,0 +1,13 @@
+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

examples/brand-logo-light-dark.yml

@@ -0,0 +1,6 @@
+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

examples/brand-logo-simple.yml

@@ -0,0 +1,4 @@
+logo:
+  small: logos/pandas/pandas_mark.svg
+  medium: logos/pandas/pandas_secondary.svg
+  large: logos/pandas/pandas.svg

examples/brand-logo-single.yml

@@ -0,0 +1 @@
+logo: posit.png

examples/brand-meta-full.yml

@@ -0,0 +1,11 @@
+meta:
+  name:
+    full: Very Big Corporation of America
+    short: VBC
+  link:
+    home: https://very-big-corp.com
+    mastodon: https://mastodon.social/@VeryBigCorpOfficial
+    github: https://github.com/Very-Big-Corp
+    linkedin: https://linkedin.com/company/very-big-corp
+    twitter: https://twitter.com/VeryBigCorp
+    facebook: https://facebook.com/Very-Big-Corp

examples/brand-meta-small.yml

@@ -0,0 +1,3 @@
+meta:
+  name: Very Big Corp. of America
+  link: https://very-big-corp.com

examples/brand-posit.yml

@@ -0,0 +1,60 @@
+meta:
+  name: 
+    full: Posit Software, PBC
+    short: Posit
+  link:
+    home: https://posit.co
+    guide: https://positpbc.atlassian.net/wiki/x/AQAgBQ
+    mastodon: https://fosstodon.org/@Posit
+    linkedin: https://www.linkedin.com/company/posit-software/
+    twitter: https://twitter.com/posit_pbc
+
+logo:
+  small: posit-icon.png
+  medium: posit.png
+  large: posit.svg
+
+color:
+  palette:
+    blue: "#447099"
+    orange: "#EE6331"
+    gray: "#404041"
+    white: "#FFFFFF"
+    teal: "#419599"
+    green: "#72994E"
+    burgundy: "#9A4665"
+  foreground: "#151515"
+  background: "#FFFFFF"
+  primary: "#447099"
+  secondary: "#707073"
+  tertiary: "#C2C2C4"
+  success: "#72994E"
+  info: "#419599"
+  warning: "#EE6331"
+  danger: "#9A4665"
+  light: "#FFFFFF"
+  dark: "#404041"
+
+typography:
+  fonts:
+    - source: google
+      family: Open Sans
+    - source: google
+      family: Fira Code
+    - source: google
+      family: Roboto Slab
+      weight: 600
+      style: normal
+      display: block
+
+  base:
+    family: "Open Sans"
+    line-height: 1.25
+    size: 1rem
+  headings:
+    family: "Roboto Slab"
+    color: primary
+    weight: 600
+  monospace:
+    family: "Fira Code"
+    size: 0.9em

examples/brand-typography-color.yml

@@ -0,0 +1,25 @@
+meta:
+  name: examples/brand-typography-color.yml
+
+color:
+  palette:
+    red: "#FF6F61"
+  primary: "#87CEEB"
+  secondary: "#50C878"
+  danger: red
+  foreground: "#1b1818"
+  background: "#f7f4f4"
+
+typography:
+  base:
+    color: foreground
+  headings:
+    color: primary
+  monospace-inline:
+    color: background
+    background-color: red
+  monospace-block:
+    color: foreground
+    background-color: background
+  link:
+    color: danger

examples/brand-typography-fonts.yml

@@ -0,0 +1,48 @@
+meta:
+  name: examples/brand-typography-fonts.yml
+color:
+  primary: "#f24242"
+typography:
+  fonts:
+    # Local files 
+    - family: Open Sans
+      source: file
+      files:
+        - path: fonts/open-sans/OpenSans-Variable.ttf
+        - path: fonts/open-sans/OpenSans-Variable-Italic.ttf
+          style: italic
+
+    # Online files
+    - family: Closed Sans
+      source: file
+      files:
+        - path: https://example.com/Closed-Sans-Bold.woff2
+          weight: bold
+        - path: https://example.com/Closed-Sans-Italic.woff2
+          style: italic
+
+    # Online Font Foundries
+    - family: Roboto Slab
+      source: google
+      weight: 600..900
+      style: normal
+      display: block
+
+    - family: Fira Code
+      source: bunny
+      # weight: [100, 200, 300, 400, 500, 600, 700, 800, 900]
+      # style: [normal, italic]
+
+  base:
+    family: Open Sans
+    line-height: 1.25
+    size: 1rem
+
+  headings:
+    family: Roboto Slab
+    color: primary
+    weight: 600
+
+  monospace:
+    family: Fira Code
+    size: 0.9em