Metadata-Version: 2.4
Name: material-design-icons
Version: 0.1.5
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 customtkinter import set_appearance_mode, set_default_color_theme, CTk, CTkButton # type: ignore

print("🚀 Launching CustomTkinter Example...")
set_appearance_mode("Dark")
set_default_color_theme("blue")

application: CTk = CTk()
application.title("Material Icons - CustomTkinter Test")
application.geometry("250x210")

provider: MaterialDesignIcons = MaterialDesignIcons(
    settings=Settings(
        weight=Weight.W500, optical_size=OpticalSize.LARGE
    ),
    style=FontStyle(
        size=32, color=Color(255, 255, 255)
    ),
)

# Outlined Pie_Chart Icon
icon_pie_chart: Icon = provider.pick(
    font_set=FontSet.Outlined,
    name=IconList.Pie_Chart,
    style=FontStyle(
        size=32, color=Color(76, 175, 80)
    ),
) 

button_pie_chart: CTkButton = CTkButton(
    application,
    text="Analytics Dashboard",
    image=icon_pie_chart.to_customtkinter(),
    compound="left",
)

button_pie_chart.pack(padx=20, pady=15) # type: ignore

# Rounded Settings Icon with Fill
icon_settings: Icon = provider.pick(
    font_set=FontSet.Rounded,
    name=IconList.Settings,
    settings=Settings(
        fill=True, weight=Weight.W700),
    style=FontStyle(
        size=32, color=Color(33, 150, 243)
    ),
)

button_settings: CTkButton = CTkButton(
    application,
    text="System Settings",
    image=icon_settings.to_customtkinter(),
    compound="left",
)

button_settings.pack(padx=20, pady=15) # type: ignore
 
# Sharp Home Icon
icon_home: Icon = provider.pick(
    font_set=FontSet.Sharp,
    name=IconList.Home,
    style=FontStyle(
        size=32, color=Color(255, 152, 0)
    ),
)

button_home: CTkButton = CTkButton(
    application,
    text="Home Screen",
    image=icon_home.to_customtkinter(),
    compound="left",
)
 
button_home.pack(padx=20, pady=15) # type: ignore
application.mainloop() # type: ignore 
```

### PyQt6 Integration

```python
from PyQt6.QtWidgets import QApplication, QPushButton, QVBoxLayout, QWidget

print("🚀 Launching PyQt6 Example...")

application: QApplication = QApplication(sys.argv)
window: QWidget = QWidget()
window.setWindowTitle("Material Icons - PyQt6 Test")
window.resize(250, 250)

vertical_layout: QVBoxLayout = QVBoxLayout()
provider: MaterialDesignIcons = MaterialDesignIcons()

# Rounded Settings Button
settings_icon: Icon = provider.pick(
    font_set=FontSet.Rounded,
    name=IconList.Settings,
    style=FontStyle(
        size=28, color=Color(0, 120, 212)
    ),
)
 
button_settings: QPushButton = QPushButton(" Settings")
button_settings.setIcon(settings_icon.to_qt())
button_settings.setStyleSheet("font-size: 1rem; margin: 0 auto")
button_settings.setFixedWidth(250)
button_settings.setFixedHeight(40)
vertical_layout.addWidget(button_settings)

# Outlined Search Button
search_icon: Icon = provider.pick(
    font_set=FontSet.Outlined,
    name=IconList.Search,
    style=FontStyle(
        size=28, color=Color(220, 53, 69)
    ),
) 

button_search: QPushButton = QPushButton(" Search Database")
button_search.setIcon(search_icon.to_qt())
button_search.setStyleSheet("font-size: 1rem; margin: 0 auto")
button_search.setFixedWidth(250)
button_search.setFixedHeight(40)
vertical_layout.addWidget(button_search)

window.setLayout(vertical_layout)
window.show()
application.exec()
```

### Flet Integration

```python
from flet import Page, Column, Image, Text, CrossAxisAlignment, MainAxisAlignment, run # type: ignore

print("🚀 Launching Flet Example...")

def main(page: Page) -> None:
    """
    Configure and render the primary Flet application page layout.

    Parameters
    ----------
    page : flet_framework.Page
        The root page container provided by Flet.

    Returns
    -------
    None
    """
    page.window.width = 300
    page.window.height = 350
    
    # Optional: Prevent user from resizing or enforce limits
    page.window.resizable = False
    page.window.min_width = 300
    page.window.min_height = 350

    page.title = "Material Icons - Flet Test"
    page.padding = 30
    page.horizontal_alignment = CrossAxisAlignment.CENTER

    provider: MaterialDesignIcons = MaterialDesignIcons()

    icons_to_render = [
        (IconList.Pie_Chart, Color(230, 81, 0), "Pie Chart"),
        (IconList.Home, Color(46, 125, 50), "Home"),
        (IconList.Settings, Color(21, 101, 192), "Settings"),
    ]

    column_controls: List[Column] = []

    for name, color, label in icons_to_render:
        icon_object = provider.pick(
            name=name,
            style=FontStyle(size=48, color=color),
        )
            
        base_64_string: str = base64.b64encode(icon_object.to_png_bytes()).decode("utf-8")
 
        column_controls.append(
            Column(
                controls=[
                    # Updated for modern Flet (v0.26+)
                    Image(
                        src=f"data:image/png;base64,{base_64_string}",
                        width=48,
                        height=48,
                    ),
                    Text(label, size=12),
                ],
                horizontal_alignment=CrossAxisAlignment.CENTER,
            )
        )

    page.add(
        Column(
            controls=column_controls, # type: ignore
            alignment=MainAxisAlignment.SPACE_EVENLY,
        )
    )

run(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**.
