Metadata-Version: 2.4
Name: material-design-icons
Version: 0.1.4
Summary: A lightweight, framework-agnostic Google Material Design Icon provider for CustomTkinter, PyQt6, Flet, and more.
Project-URL: Homepage, https://github.com/aceburgundy/python-material-design-icons
Project-URL: Repository, https://github.com/aceburgundy/python-material-design-icons
Project-URL: Issues, https://github.com/aceburgundy/python-material-design-icons/issues
Author-email: AceBurgundy <Samadriansabalo99@gmail.com>
License: MIT
Keywords: customtkinter,flet,gui,icons,material-design,pillow,pyqt6,pyside6,tkinter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.9
Requires-Dist: pillow>=9.0.0
Provides-Extra: all
Requires-Dist: customtkinter>=5.0.0; extra == 'all'
Requires-Dist: flet>=0.20.0; extra == 'all'
Requires-Dist: pyqt6>=6.0.0; extra == 'all'
Requires-Dist: pytest>=7.0.0; extra == 'all'
Provides-Extra: customtkinter
Requires-Dist: customtkinter>=5.0.0; extra == 'customtkinter'
Provides-Extra: flet
Requires-Dist: flet>=0.20.0; extra == 'flet'
Provides-Extra: pyqt6
Requires-Dist: pyqt6>=6.0.0; extra == 'pyqt6'
Description-Content-Type: text/markdown

# 🎨 Python Material Design Icons ✨

[![PyPI version](https://img.shields.io/badge/pip%20install-material__design__icons-blue.svg)](https://github.com/aceburgundy/python-material-design-icons)
[![Python Version](https://img.shields.io/badge/python-3.8%2B-brightgreen.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> 🚀 **Python Material Design Icons** brings Google's official **Material Symbols & Icons** directly to Python desktop and web GUI applications! Fully framework-agnostic with built-in export wrappers for **CustomTkinter**, **PyQt6**, **Flet**, **PIL**, and raw **PNG byte streams**.

## 📌 Features

* 📦 **Zero GUI Lock-In:** Render icons seamlessly inside CustomTkinter, PyQt6/PySide6, Flet, Tkinter, Pygame, or Kivy!
* ⚡ **Ultra-Lightweight Build:** Powered by Variable TrueType Fonts (`.ttf`) to bundle thousands of icons across all weights and optical sizes into a tiny package footprint (~6 MB) without bloated Webpack CSS/font bundles.
* 🛠️ **Granular Customization:** Full control over `Weight` (100–700), `Grade` (-25 to 200), `OpticalSize` (20–64), `Fill`, custom `Color` (RGB/RGBA), and sizing.
* 🎯 **Smart Parameter Precedence:** Flexible multi-level defaults across instances and method calls.
* 🔤 **Type Hinted & Enum Safe:** IntelliSense support out of the box with `IconList`, `FontSet`, `Weight`, `Grade`, and `OpticalSize`.

## 📸 Framework Showcase

<p align="center">
  <img src="images/CustomTkinter.png" height="180" alt="CustomTkinter Integration Showcase" />
  <img src="images/PyQT6.png" height="180" alt="PyQt6 Integration Showcase" />
  <img src="images/Flet.png" height="180" alt="Flet Integration Showcase" />
  <img src="images/Tkinter.png" height="180" alt="Tkinter Integration Showcase" />
</p>

## 📥 Installation

```bash
pip install material_design_icons
```

Here are the complete implementations for **`material_design_icons/__init__.py`**, **`pyproject.toml`**, and a comprehensive, emoji-packed **`README.md`** tailored directly to your specifications.

## ⚙️ Architecture & Parameter Precedence

When retrieving an icon via `MaterialDesignIcons.pick()`, style and rendering settings resolve using a strict 3-tier hierarchy:

```
┌───────────────────────────────────────────────┐
│ 1. pick(...) Method Arguments (Highest)       │
├───────────────────────────────────────────────┤
│ 2. MaterialDesignIcons(...) Instance Defaults │
├───────────────────────────────────────────────┤
│ 3. Built-in Library Defaults (Lowest)         │
└───────────────────────────────────────────────┘

```

* **Method Parameters:** Overrides instance defaults if explicitly supplied to `pick()`.

* **Instance Parameters:** Default values set when instantiating `MaterialDesignIcons(settings=..., style=...)`.

* **Built-in Defaults:**
* `FontSet`: `FontSet.Outlined`
* `Settings`: `fill=False`, `weight=Weight.W400`, `grade=Grade.DEFAULT`, `optical_size=OpticalSize.MEDIUM`
* `FontStyle`: `size=48`, `color=Color(0, 0, 0)`



## 📖 API Reference

### 1. `Settings`

Controls font variation axes (VF) for Material Symbols.

| Field | Type | Default | Options |
| --- | --- | --- | --- |
| `fill` | `Optional[bool]` | `False` | `True`, `False` |
| `weight` | `Optional[Weight]` | `Weight.W400` | `Weight.W100` through `Weight.W700` (increments of 100) |
| `grade` | `Optional[Grade]` | `Grade.DEFAULT` | `Grade.LOW` (`-25`), `Grade.DEFAULT` (`0`), `Grade.HIGH` (`200`) |
| `optical_size` | `Optional[OpticalSize]` | `OpticalSize.MEDIUM` | `OpticalSize.DEFAULT` (`20`), `SMALL` (`24`), `MEDIUM` (`48`), `LARGE` (`64`) |

```python
from material_design_icons.settings import Settings, Weight, Grade, OpticalSize

# Custom Settings Definition
settings = Settings(
    fill=True,
    weight=Weight.W600,
    grade=Grade.HIGH,        # String key aliases supported: Grade.high
    optical_size=OpticalSize.LARGE # String key aliases supported: OpticalSize.large
)

```

### 2. `FontStyle` & `Color`

Controls visual rendering attributes (size, color, alpha).

```python
from material_design_icons.styles import FontStyle, Color

# Define Color using RGB or RGBA values
brand_color = Color(red=0, green=120, blue=212, alpha=255)

# Style configuration
style = FontStyle(size=32, color=brand_color)

```

### 3. Core Classes & Enums

```python
from material_design_icons.core import MaterialDesignIcons, FontSet, IconList

# Font Sets available
FontSet.Outlined  # Default
FontSet.Rounded
FontSet.Sharp

# Instantiate manager with global defaults
md_icons = MaterialDesignIcons(settings=settings, style=style)

```

## 🚀 Framework Integration Examples

### Customtkinter Integration

```python
from typing import Any

import customtkinter as ctk
from material_design_icons.core import IconList, MaterialDesignIcons
from material_design_icons.styles import Color, FontStyle

"""
CustomTkinter Application Interface Module.

This script initializes a CustomTkinter window and renders a button displaying
a Material Design pie chart icon with textual label.
"""

# Initialize the main CustomTkinter application window
application: ctk.CTk = ctk.CTk()

# Any required here: external third-party library returns custom non-standard object instance
material_design_icons_provider: MaterialDesignIcons = MaterialDesignIcons()

# Fetch and configure the requested Material Design icon
icon: Any = material_design_icons_provider.pick(
    name=IconList.PieChart,
    style=FontStyle(size=32, color=Color(255, 255, 255)),
)

# Convert icon to CustomTkinter image format for UI button binding
customtkinter_image: Any = icon.to_customtkinter()

# Instantiate the UI button with text and image components
analytics_button: ctk.CTkButton = ctk.CTkButton(
    application,
    text="Analytics",
    image=customtkinter_image,
    compound="left",
)

# Apply layout padding and place the button on the main application frame
analytics_button.pack(padx=20, pady=20)

```

### PyQt6 Integration

```python
from typing import Any

from PyQt6.QtGui import QIcon
from PyQt6.QtWidgets import QApplication, QPushButton
from material_design_icons.core import FontSet, IconList, MaterialDesignIcons
from material_design_icons.styles import Color, FontStyle

# Initialize the Qt application instance
application: QApplication = QApplication([])

# Initialize the Material Design icon manager
material_design_icons: MaterialDesignIcons = MaterialDesignIcons()

# Generate the requested icon with custom visual properties
# (font set, icon name, size, and RGB color)
settings_icon: Any = material_design_icons.pick(
    font_set=FontSet.Rounded,
    name=IconList.Settings,
    style=FontStyle(size=24, color=Color(0, 120, 212)),
)

# Convert the Material Design icon to a Qt QIcon representation
qt_settings_icon: QIcon = settings_icon.to_qt()

# Create the button control and set its displayed icon and text label
settings_button: QPushButton = QPushButton("Settings")
settings_button.setIcon(qt_settings_icon)

# Display the push button on screen
settings_button.show()

```

### Flet Integration

```python
import base64
from typing import Any
import flet
from material_design_icons.core import IconList, MaterialDesignIcons
from material_design_icons.styles import Color, FontStyle


def main(page: flet.Page) -> None:
    """
    Render a Material Design icon inside a Flet application page.

    Parameters
    ----------
    page : flet.Page
        The primary Flet page instance onto which UI controls are added.

    Returns
    -------
    None
    """
    # Any required here: external library returns untyped icon object instance
    material_design_icons: MaterialDesignIcons = MaterialDesignIcons()

    # Any required here: third-party library method returns an unannotated Icon object
    icon_instance: Any = material_design_icons.pick(
        name=IconList.PieChart,
        style=FontStyle(size=48, color=Color(230, 81, 0)),
    )

    # Convert generated icon PNG byte stream to base64 data URI string
    png_bytes: bytes = icon_instance.to_png_bytes()
    base64_encoded_bytes: bytes = base64.b64encode(png_bytes)
    image_base64_string: str = base64_encoded_bytes.decode()

    # Pass data URI to Flet Image src control
    image_control: flet.Image = flet.Image(
        src=f"data:image/png;base64,{image_base64_string}"
    )
    page.add(image_control)


flet.app(target=main)

```

## ⚡ Technical Highlights & Footprint Optimization

* **Variable TrueType Fonts:** Instead of storing thousands of static SVG/PNG files, the package bundles **Google Variable TTF Fonts** (`MaterialSymbolsOutlined.ttf`, `MaterialSymbolsRounded.ttf`, `MaterialSymbolsSharp.ttf`).
* **Zero CSS Overhead:** Resolves the common web build size issue (where importing standard CSS files forces bundlers to include all font subsets).
* **High Performance Rendering:** Uses vector rendering via Pillow (`ImageDraw.text`) anchored directly on TTF glyph codepoints to render crystal-clear icons at arbitrary resolutions.

## 👤 Author & Maintainer

* **Author:** AceBurgundy
* **Email:** [Samadriansabalo99@gmail.com](https://www.google.com/search?q=mailto%3ASamadriansabalo99%40gmail.com)
* **GitHub Repository:** [aceburgundy/python-material-design-icons](https://github.com/aceburgundy/python-material-design-icons)

## 📄 License

This project is licensed under the **MIT License**. Google Material Design Icons/Symbols are licensed under the **Apache License 2.0**.
