| Name | q-materialise JSON |
| Version |
0.1.7
JSON |
| download |
| home_page | None |
| Summary | An enhanced Material Design stylesheet library for Qt (PyQt5, PyQt6, PySide2 and PySide6) |
| upload_time | 2025-07-26 19:27:25 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 Arched dev
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
qt
material
stylesheet
style
gui
pyqt
pyside
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# QMaterialise
QMaterialise is a modern Material Design stylesheet library for Qt
applications written in Python. It is a ground‑up redesign of the
[qt‑material](https://github.com/UN‑GCPDS/qt‑material) library by UN‑GCPDS, and we’re
grateful for their original work. It draws inspiration from the
Material Design specification and provides a clean and flexible
implementation with:
* **Cross‑binding support** – works with PyQt5, PyQt6, PySide2 and
PySide6. At runtime the library automatically selects whichever
binding is installed.
* **Comprehensive colour palettes** – more Material Design colours
are built in, including all of the primary swatches and their
tints/shades.
* **Easy customisation** – generate new styles from a few colours or
load predefined styles shipped with the package. Styles are
expressed as JSON dictionaries, making them easy to edit and share.
* **Dynamic theming** – apply a new style to a running application
without restarting it and switch between dark and light variants on
the fly.
* **Runtime extras** – override button colours, fonts, density scale
and more by passing an extra dictionary to the inject_style
function.
* **Export to QSS** – write the generated stylesheet to a `.qss`
file so it can be used directly in Qt Designer or C++ projects.
Material Design is a design system created by Google. QMaterialise
provides a coherent set of colours and styles that conform to the
specification while still giving you freedom to customise the look and
feel of your application.
## Installation
QMaterialise can be installed from PyPI. Depending on which Qt
binding you intend to use you should also install the corresponding
optional dependency:
```bash
# Install the core library
pip install "q-materialise"
```
## Quick start
The simplest way to style your application is to call
`inject_style()` after you create your `QApplication` instance. This
function accepts either the name of one of the built‑in styles or a
custom `Style` object:
```python
import sys
from q_materialise import inject_style, list_styles
try:
# Try to import your preferred Qt binding
from PySide6 import QtWidgets
except ImportError:
from q_materialise.binding import QtWidgets # internal helper
app = QtWidgets.QApplication(sys.argv)
window = QtWidgets.QMainWindow()
# Print the available built‑in styles
print(list_styles())
inject_style(app, style="indigo_twilight")
window.setWindowTitle("QMaterialise Example")
window.resize(480, 320)
window.show()
sys.exit(app.exec())
```
To customise individual aspects of the style, pass an extra
dictionary. For example, to change the colours of different classes
of `QPushButton`:
```python
extra = {
"danger": "#dc3545",
"warning": "#ffc107",
"success": "#198754",
"info": "#0d6efd",
"font_family": "Roboto",
"font_size": "14px",
"density_scale": 0,
}
inject_style(app, style="sapphire_day", extra=extra)
```
Button classes are attached by setting the `class` property on the
widget:
```python
push_button.setProperty("class", "danger")
```
## Generating custom styles
To create a completely new style programmatically, use the
`generate_style()` function. Pass your primary and secondary base
colours and indicate whether the style should be dark or light. The
function returns a `Style` instance with sensible tints and shades
computed for you:
```python
from q_materialise import generate_style, inject_style
my_style = generate_style(
name="my_custom_dark",
primary="#9c27b0", # purple
secondary="#ffeb3b", # yellow
is_dark=True,
)
inject_style(app, style=my_style)
```
Styles are plain data classes and can be serialised to and from JSON.
For example:
```python
import json
json_string = my_style.to_json(indent=4)
with open("my_style.json", "w", encoding="utf-8") as f:
f.write(json_string)
# Later
from q_materialise import Style
with open("my_style.json", encoding="utf-8") as f:
other_style = Style.from_json(f.read())
```
## Listing styles
Built‑in styles are stored as JSON files in the package. You can list
them at runtime with `list_styles()` and load one with
`get_style(name)`:
```python
from q_materialise import list_styles, get_style
print(list_styles())
indigo_style = get_style("indigo_twilight")
```
## Exporting a stylesheet
If you want to use the generated stylesheet outside of Python you can
export it to a `.qss` file. The `export_style()` function takes the
name of the style, the destination file and optional extras:
```python
from q_materialise import export_style
export_style(style="indigo_twilight", qss_path="indigo_twilight.qss")
```
## Documentation
Full documentation is published online and can be accessed at:
[https://lewis-morris.github.io/qmaterialise](https://lewis-morris.github.io/qmaterialise)
## Contributing
Contributions are welcome! If you find a bug or have an idea for a
feature, please open an issue or submit a pull request. Feel free to
add new styles by placing a JSON file in the
`src/q_materialise/styles` directory.
> **Note:** q-materialise is as a redesign of the
> [qt‑material](https://github.com/UN‑GCPDS/qt‑material) project—
> thanks to the UN‑GCPDS team.
Raw data
{
"_id": null,
"home_page": null,
"name": "q-materialise",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "qt, material, stylesheet, style, gui, pyqt, pyside",
"author": null,
"author_email": "\"Lewis (arched.dev)\" <lewis@arched.dev>",
"download_url": "https://files.pythonhosted.org/packages/32/e7/186451f8d0e619624e51e2759f3bab3c1cb954733bbc0f40b53c38b83755/q_materialise-0.1.7.tar.gz",
"platform": null,
"description": "# QMaterialise\n\nQMaterialise is a modern Material Design stylesheet library for Qt\napplications written in Python. It is a ground\u2011up redesign of the\n[qt\u2011material](https://github.com/UN\u2011GCPDS/qt\u2011material) library by UN\u2011GCPDS, and we\u2019re\ngrateful for their original work. It draws inspiration from the\nMaterial Design specification and provides a clean and flexible\nimplementation with:\n\n* **Cross\u2011binding support** \u2013 works with PyQt5, PyQt6, PySide2 and\n PySide6. At runtime the library automatically selects whichever\n binding is installed.\n* **Comprehensive colour palettes** \u2013 more Material Design colours\n are built in, including all of the primary swatches and their\n tints/shades.\n* **Easy customisation** \u2013 generate new styles from a few colours or\n load predefined styles shipped with the package. Styles are\n expressed as JSON dictionaries, making them easy to edit and share.\n* **Dynamic theming** \u2013 apply a new style to a running application\n without restarting it and switch between dark and light variants on\n the fly.\n* **Runtime extras** \u2013 override button colours, fonts, density scale\n and more by passing an extra dictionary to the inject_style\n function.\n* **Export to QSS** \u2013 write the generated stylesheet to a `.qss`\n file so it can be used directly in Qt Designer or C++ projects.\n\nMaterial Design is a design system created by Google. QMaterialise\nprovides a coherent set of colours and styles that conform to the\nspecification while still giving you freedom to customise the look and\nfeel of your application.\n\n## Installation\n\nQMaterialise can be installed from PyPI. Depending on which Qt\nbinding you intend to use you should also install the corresponding\noptional dependency:\n\n```bash\n# Install the core library\npip install \"q-materialise\"\n\n```\n\n\n## Quick start\n\nThe simplest way to style your application is to call\n`inject_style()` after you create your `QApplication` instance. This\nfunction accepts either the name of one of the built\u2011in styles or a\ncustom `Style` object:\n\n```python\nimport sys\nfrom q_materialise import inject_style, list_styles\n\ntry:\n # Try to import your preferred Qt binding\n from PySide6 import QtWidgets\nexcept ImportError:\n from q_materialise.binding import QtWidgets # internal helper\n\napp = QtWidgets.QApplication(sys.argv)\nwindow = QtWidgets.QMainWindow()\n\n# Print the available built\u2011in styles\nprint(list_styles())\n\ninject_style(app, style=\"indigo_twilight\")\nwindow.setWindowTitle(\"QMaterialise Example\")\nwindow.resize(480, 320)\nwindow.show()\nsys.exit(app.exec())\n```\n\nTo customise individual aspects of the style, pass an extra\ndictionary. For example, to change the colours of different classes\nof `QPushButton`:\n\n```python\nextra = {\n \"danger\": \"#dc3545\",\n \"warning\": \"#ffc107\",\n \"success\": \"#198754\",\n \"info\": \"#0d6efd\",\n \"font_family\": \"Roboto\",\n \"font_size\": \"14px\",\n \"density_scale\": 0,\n}\n\ninject_style(app, style=\"sapphire_day\", extra=extra)\n```\n\nButton classes are attached by setting the `class` property on the\nwidget:\n\n```python\npush_button.setProperty(\"class\", \"danger\")\n```\n\n## Generating custom styles\n\nTo create a completely new style programmatically, use the\n`generate_style()` function. Pass your primary and secondary base\ncolours and indicate whether the style should be dark or light. The\nfunction returns a `Style` instance with sensible tints and shades\ncomputed for you:\n\n```python\nfrom q_materialise import generate_style, inject_style\n\nmy_style = generate_style(\n name=\"my_custom_dark\",\n primary=\"#9c27b0\", # purple\n secondary=\"#ffeb3b\", # yellow\n is_dark=True,\n)\n\ninject_style(app, style=my_style)\n```\n\nStyles are plain data classes and can be serialised to and from JSON.\nFor example:\n\n```python\nimport json\n\njson_string = my_style.to_json(indent=4)\nwith open(\"my_style.json\", \"w\", encoding=\"utf-8\") as f:\n f.write(json_string)\n\n# Later\nfrom q_materialise import Style\n\nwith open(\"my_style.json\", encoding=\"utf-8\") as f:\n other_style = Style.from_json(f.read())\n```\n\n## Listing styles\n\nBuilt\u2011in styles are stored as JSON files in the package. You can list\nthem at runtime with `list_styles()` and load one with\n`get_style(name)`:\n\n```python\nfrom q_materialise import list_styles, get_style\n\nprint(list_styles())\nindigo_style = get_style(\"indigo_twilight\")\n```\n\n## Exporting a stylesheet\n\nIf you want to use the generated stylesheet outside of Python you can\nexport it to a `.qss` file. The `export_style()` function takes the\nname of the style, the destination file and optional extras:\n\n```python\nfrom q_materialise import export_style\n\nexport_style(style=\"indigo_twilight\", qss_path=\"indigo_twilight.qss\")\n```\n\n## Documentation\n\nFull documentation is published online and can be accessed at:\n\n[https://lewis-morris.github.io/qmaterialise](https://lewis-morris.github.io/qmaterialise)\n\n\n## Contributing\n\nContributions are welcome! If you find a bug or have an idea for a\nfeature, please open an issue or submit a pull request. Feel free to\nadd new styles by placing a JSON file in the\n`src/q_materialise/styles` directory.\n\n> **Note:** q-materialise is as a redesign of the\n> [qt\u2011material](https://github.com/UN\u2011GCPDS/qt\u2011material) project\u2014\n> thanks to the UN\u2011GCPDS team.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Arched dev\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "An enhanced Material Design stylesheet library for Qt (PyQt5, PyQt6, PySide2 and PySide6)",
"version": "0.1.7",
"project_urls": null,
"split_keywords": [
"qt",
" material",
" stylesheet",
" style",
" gui",
" pyqt",
" pyside"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "be01fe611768c208093c80b38e72bd26118a79525ff4c4eeef6212a4bc2a1cee",
"md5": "9a11956c12deb26aa38809989d07eaab",
"sha256": "f76d53c5a04f266b6bc1d9851cace3e1171cf7bded20ba8425f4fff5ff6796e9"
},
"downloads": -1,
"filename": "q_materialise-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a11956c12deb26aa38809989d07eaab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 42088,
"upload_time": "2025-07-26T19:27:24",
"upload_time_iso_8601": "2025-07-26T19:27:24.726576Z",
"url": "https://files.pythonhosted.org/packages/be/01/fe611768c208093c80b38e72bd26118a79525ff4c4eeef6212a4bc2a1cee/q_materialise-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "32e7186451f8d0e619624e51e2759f3bab3c1cb954733bbc0f40b53c38b83755",
"md5": "2afb832097dface6443160158b23d061",
"sha256": "63021ae27ee2e3b2fd77258cf02d0a44ec5b1f0775f06177a237d6c0bb915aa4"
},
"downloads": -1,
"filename": "q_materialise-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "2afb832097dface6443160158b23d061",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 34161,
"upload_time": "2025-07-26T19:27:25",
"upload_time_iso_8601": "2025-07-26T19:27:25.814156Z",
"url": "https://files.pythonhosted.org/packages/32/e7/186451f8d0e619624e51e2759f3bab3c1cb954733bbc0f40b53c38b83755/q_materialise-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 19:27:25",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "q-materialise"
}
