| Name | python-lucide JSON |
| Version |
0.2.2
JSON |
| download |
| home_page | None |
| Summary | A Python package for working with Lucide icons |
| upload_time | 2025-07-28 17:41:26 |
| maintainer | None |
| docs_url | None |
| author | Mike Macpherson |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
lucide
icons
svg
sqlite
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# python-lucide
A Python package that provides easy access to all [Lucide
icons](https://lucide.dev/) as SVG strings. Just import and use any Lucide icon
in your Python projects, with no javascript in sight.
## Features
- 🎨 **Access 1000+ Lucide icons** directly from Python
- 🛠**Customize icons** with classes, sizes, colors, and other SVG attributes
- 🚀 **Framework-friendly** with examples for FastHTML, Flask, Django, and more
- 📦 **Lightweight** with minimal dependencies
- 🔧 **Customizable icon sets** - include only the icons you need
## Installation
```bash
pip install python-lucide
```
This installs the package with a pre-built database of all Lucide icons, ready to use immediately.
## Quick Start
```python
from lucide import lucide_icon
# Get an icon
svg = lucide_icon("house")
# Add CSS classes
svg = lucide_icon("settings", cls="icon icon-settings")
# Customize size
svg = lucide_icon("arrow-up", width="32", height="32")
# Customize colors (stroke for outline, fill for interior)
svg = lucide_icon("heart", stroke="red", fill="pink")
# Customize stroke properties
svg = lucide_icon("chart-line", stroke_width="3", stroke_linecap="round")
```
### Icon Customization
All Lucide icons use `stroke` for their outline color and `fill` for their interior color:
```python
# Looking for how to change colors? Use stroke and fill:
lucide_icon("user", stroke="blue") # Blue outline
lucide_icon("user", fill="currentColor") # Inherit color from CSS
lucide_icon("user", stroke="#ff6b6b") # Hex colors work too
```
## Framework Integration Examples
### FastHTML
```python
from fasthtml.common import *
from lucide import lucide_icon
app, rt = fast_app()
@rt('/')
def get():
return Titled("Hello Icons",
H1("Welcome"),
# Wrap icon output in NotStr to prevent HTML escaping
NotStr(lucide_icon("house", cls="icon")),
P("This is a simple FastHTML app with Lucide icons.")
)
serve()
```
### Flask
```python
from flask import Flask
from lucide import lucide_icon
app = Flask(__name__)
@app.route('/icons/<icon_name>')
def serve_icon(icon_name):
svg = lucide_icon(icon_name, cls="icon", stroke="currentColor")
return svg, 200, {'Content-Type': 'image/svg+xml'}
```
### Django
```python
# In your views.py
from django.http import HttpResponse
from lucide import lucide_icon
def icon_view(request, icon_name):
svg = lucide_icon(icon_name, cls="icon-lg", width="32", height="32")
return HttpResponse(svg, content_type='image/svg+xml')
# In your templates (as a template tag)
from django import template
from django.utils.safestring import mark_safe
from lucide import lucide_icon
register = template.Library()
@register.simple_tag
def icon(name, **kwargs):
return mark_safe(lucide_icon(name, **kwargs))
```
### FastAPI
```python
from fastapi import FastAPI
from fastapi.responses import Response
from lucide import lucide_icon
app = FastAPI()
@app.get("/icons/{icon_name}")
def get_icon(icon_name: str, size: int = 24, color: str = "currentColor"):
svg = lucide_icon(icon_name, width=size, height=size, stroke=color)
return Response(content=svg, media_type="image/svg+xml")
```
## API Reference
### `lucide_icon()`
Retrieves and customizes a Lucide icon.
```python
lucide_icon(
icon_name: str,
cls: str = "",
fallback_text: str | None = None,
width: str | int | None = None,
height: str | int | None = None,
fill: str | None = None,
stroke: str | None = None,
stroke_width: str | int | None = None,
stroke_linecap: str | None = None,
stroke_linejoin: str | None = None,
) -> str
```
**Parameters:**
- `icon_name`: Name of the Lucide icon to retrieve
- `cls`: CSS classes to add to the SVG element (space-separated)
- `fallback_text`: Text to display if the icon is not found
- `width`: Width of the SVG element
- `height`: Height of the SVG element
- `fill`: Fill color for the icon
- `stroke`: Stroke color for the icon (outline color)
- `stroke_width`: Width of the stroke
- `stroke_linecap`: How the ends of strokes are rendered ("round", "butt", "square")
- `stroke_linejoin`: How corners are rendered ("round", "miter", "bevel")
**Returns:** SVG string
**Example:**
```python
# Full customization example
icon = lucide_icon(
"activity",
cls="icon icon-activity animated",
width=48,
height=48,
stroke="rgb(59, 130, 246)",
stroke_width=2.5,
stroke_linecap="round",
stroke_linejoin="round"
)
```
### `get_icon_list()`
Returns a list of all available icon names.
```python
from lucide import get_icon_list
icons = get_icon_list()
print(f"Available icons: {len(icons)}")
print(icons[:5]) # ['activity', 'airplay', 'alarm-check', ...]
```
## Advanced Usage
### Building a Custom Icon Set
If you want to include only specific icons or use a different version of Lucide:
```bash
# Build with specific icons only
lucide-db -i home,settings,user,heart,star -o custom-icons.db
# Use a specific Lucide version
lucide-db -t 0.350.0 -o lucide-v0.350.0.db
# Build from a file listing icon names
echo -e "home\nsettings\nuser" > my-icons.txt
lucide-db -f my-icons.txt -o my-icons.db
```
### Using a Custom Database
Set the `LUCIDE_DB_PATH` environment variable:
```bash
export LUCIDE_DB_PATH=/path/to/custom-icons.db
python your-app.py
```
Or configure it in your Python code:
```python
import os
os.environ['LUCIDE_DB_PATH'] = '/path/to/custom-icons.db'
from lucide import lucide_icon
# Will now use your custom database
```
## Development
This project uses `uv` for fast dependency management and `pre-commit` for code quality.
### Setup
```bash
# Clone the repository
git clone https://github.com/mmacpherson/python-lucide.git
cd python-lucide
# Create a virtual environment and install dependencies
make env
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install pre-commit hooks
make install-hooks
# Run tests
make test
```
### Rebuilding the Icon Database
```bash
# Rebuild with latest Lucide icons
make lucide-db
# Rebuild with specific version
make lucide-db TAG=0.350.0
# Check if version updates are available
make check-lucide-version
```
### Version Checking and Automation
The project includes automated version checking and update capabilities:
```bash
# Check for Lucide version updates and artifact status
make check-lucide-version
# Alternative: Use the CLI command directly
uv run check-lucide-version
```
**Weekly Automation**: The repository automatically checks for new Lucide releases every Monday and creates update PRs when new versions are available.
### Release Process
This project follows a manual release process:
1. **Update version** in `pyproject.toml`:
```bash
# Create release branch
git checkout -b release/v0.2.0
# Edit pyproject.toml to bump version
# version = "0.2.0"
# Commit and push
git add pyproject.toml
git commit -m "Bump version to 0.2.0"
git push -u origin release/v0.2.0
```
2. **Create and merge PR** for the version bump
3. **Trigger publishing workflow**:
- Go to [Actions](../../actions/workflows/publish.yml)
- Click "Run workflow"
- Select the main branch
- Click "Run workflow"
4. **Automatic publishing**: The `publish.yml` workflow builds and publishes the package to PyPI using trusted publishing.
## How It Works
The package comes with a pre-built SQLite database containing all Lucide icons. When you call `lucide_icon()`, it fetches the icon's SVG from the database and applies your customizations. This approach means:
- **Fast**: Icons are loaded from an efficient SQLite database
- **Offline**: No internet connection required at runtime
- **Customizable**: Build your own database with just the icons you need
- **Maintainable**: Update to newer Lucide versions by rebuilding the database
## License
This project is licensed under the MIT License - see the LICENSE file for details.
The Lucide icons themselves are also MIT licensed - see [Lucide's license](https://github.com/lucide-icons/lucide/blob/main/LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "python-lucide",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "lucide, icons, svg, sqlite",
"author": "Mike Macpherson",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/49/20/1e0bf2a1bffc8a49939d8b40550919862df88e4d5bbfa749cb3cab8383e0/python_lucide-0.2.2.tar.gz",
"platform": null,
"description": "# python-lucide\n\nA Python package that provides easy access to all [Lucide\nicons](https://lucide.dev/) as SVG strings. Just import and use any Lucide icon\nin your Python projects, with no javascript in sight.\n\n## Features\n- \ud83c\udfa8 **Access 1000+ Lucide icons** directly from Python\n- \ud83d\udee0 **Customize icons** with classes, sizes, colors, and other SVG attributes\n- \ud83d\ude80 **Framework-friendly** with examples for FastHTML, Flask, Django, and more\n- \ud83d\udce6 **Lightweight** with minimal dependencies\n- \ud83d\udd27 **Customizable icon sets** - include only the icons you need\n\n## Installation\n```bash\npip install python-lucide\n```\nThis installs the package with a pre-built database of all Lucide icons, ready to use immediately.\n\n## Quick Start\n```python\nfrom lucide import lucide_icon\n\n# Get an icon\nsvg = lucide_icon(\"house\")\n\n# Add CSS classes\nsvg = lucide_icon(\"settings\", cls=\"icon icon-settings\")\n\n# Customize size\nsvg = lucide_icon(\"arrow-up\", width=\"32\", height=\"32\")\n\n# Customize colors (stroke for outline, fill for interior)\nsvg = lucide_icon(\"heart\", stroke=\"red\", fill=\"pink\")\n\n# Customize stroke properties\nsvg = lucide_icon(\"chart-line\", stroke_width=\"3\", stroke_linecap=\"round\")\n```\n\n### Icon Customization\nAll Lucide icons use `stroke` for their outline color and `fill` for their interior color:\n```python\n# Looking for how to change colors? Use stroke and fill:\nlucide_icon(\"user\", stroke=\"blue\") # Blue outline\nlucide_icon(\"user\", fill=\"currentColor\") # Inherit color from CSS\nlucide_icon(\"user\", stroke=\"#ff6b6b\") # Hex colors work too\n```\n\n## Framework Integration Examples\n\n### FastHTML\n```python\nfrom fasthtml.common import *\nfrom lucide import lucide_icon\n\napp, rt = fast_app()\n\n@rt('/')\ndef get():\n return Titled(\"Hello Icons\",\n H1(\"Welcome\"),\n # Wrap icon output in NotStr to prevent HTML escaping\n NotStr(lucide_icon(\"house\", cls=\"icon\")),\n P(\"This is a simple FastHTML app with Lucide icons.\")\n )\n\nserve()\n```\n\n### Flask\n```python\nfrom flask import Flask\nfrom lucide import lucide_icon\n\napp = Flask(__name__)\n\n@app.route('/icons/<icon_name>')\ndef serve_icon(icon_name):\n svg = lucide_icon(icon_name, cls=\"icon\", stroke=\"currentColor\")\n return svg, 200, {'Content-Type': 'image/svg+xml'}\n```\n\n### Django\n```python\n# In your views.py\nfrom django.http import HttpResponse\nfrom lucide import lucide_icon\n\ndef icon_view(request, icon_name):\n svg = lucide_icon(icon_name, cls=\"icon-lg\", width=\"32\", height=\"32\")\n return HttpResponse(svg, content_type='image/svg+xml')\n\n# In your templates (as a template tag)\nfrom django import template\nfrom django.utils.safestring import mark_safe\nfrom lucide import lucide_icon\n\nregister = template.Library()\n\n@register.simple_tag\ndef icon(name, **kwargs):\n return mark_safe(lucide_icon(name, **kwargs))\n```\n\n### FastAPI\n```python\nfrom fastapi import FastAPI\nfrom fastapi.responses import Response\nfrom lucide import lucide_icon\n\napp = FastAPI()\n\n@app.get(\"/icons/{icon_name}\")\ndef get_icon(icon_name: str, size: int = 24, color: str = \"currentColor\"):\n svg = lucide_icon(icon_name, width=size, height=size, stroke=color)\n return Response(content=svg, media_type=\"image/svg+xml\")\n```\n\n## API Reference\n\n### `lucide_icon()`\nRetrieves and customizes a Lucide icon.\n```python\nlucide_icon(\n icon_name: str,\n cls: str = \"\",\n fallback_text: str | None = None,\n width: str | int | None = None,\n height: str | int | None = None,\n fill: str | None = None,\n stroke: str | None = None,\n stroke_width: str | int | None = None,\n stroke_linecap: str | None = None,\n stroke_linejoin: str | None = None,\n) -> str\n```\n**Parameters:**\n- `icon_name`: Name of the Lucide icon to retrieve\n- `cls`: CSS classes to add to the SVG element (space-separated)\n- `fallback_text`: Text to display if the icon is not found\n- `width`: Width of the SVG element\n- `height`: Height of the SVG element\n- `fill`: Fill color for the icon\n- `stroke`: Stroke color for the icon (outline color)\n- `stroke_width`: Width of the stroke\n- `stroke_linecap`: How the ends of strokes are rendered (\"round\", \"butt\", \"square\")\n- `stroke_linejoin`: How corners are rendered (\"round\", \"miter\", \"bevel\")\n\n**Returns:** SVG string\n\n**Example:**\n```python\n# Full customization example\nicon = lucide_icon(\n \"activity\",\n cls=\"icon icon-activity animated\",\n width=48,\n height=48,\n stroke=\"rgb(59, 130, 246)\",\n stroke_width=2.5,\n stroke_linecap=\"round\",\n stroke_linejoin=\"round\"\n)\n```\n\n### `get_icon_list()`\nReturns a list of all available icon names.\n```python\nfrom lucide import get_icon_list\n\nicons = get_icon_list()\nprint(f\"Available icons: {len(icons)}\")\nprint(icons[:5]) # ['activity', 'airplay', 'alarm-check', ...]\n```\n\n## Advanced Usage\n\n### Building a Custom Icon Set\nIf you want to include only specific icons or use a different version of Lucide:\n```bash\n# Build with specific icons only\nlucide-db -i home,settings,user,heart,star -o custom-icons.db\n\n# Use a specific Lucide version\nlucide-db -t 0.350.0 -o lucide-v0.350.0.db\n\n# Build from a file listing icon names\necho -e \"home\\nsettings\\nuser\" > my-icons.txt\nlucide-db -f my-icons.txt -o my-icons.db\n```\n\n### Using a Custom Database\nSet the `LUCIDE_DB_PATH` environment variable:\n```bash\nexport LUCIDE_DB_PATH=/path/to/custom-icons.db\npython your-app.py\n```\nOr configure it in your Python code:\n```python\nimport os\nos.environ['LUCIDE_DB_PATH'] = '/path/to/custom-icons.db'\n\nfrom lucide import lucide_icon\n# Will now use your custom database\n```\n\n## Development\nThis project uses `uv` for fast dependency management and `pre-commit` for code quality.\n\n### Setup\n```bash\n# Clone the repository\ngit clone https://github.com/mmacpherson/python-lucide.git\ncd python-lucide\n\n# Create a virtual environment and install dependencies\nmake env\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n# Install pre-commit hooks\nmake install-hooks\n\n# Run tests\nmake test\n```\n\n### Rebuilding the Icon Database\n```bash\n# Rebuild with latest Lucide icons\nmake lucide-db\n\n# Rebuild with specific version\nmake lucide-db TAG=0.350.0\n\n# Check if version updates are available\nmake check-lucide-version\n```\n\n### Version Checking and Automation\nThe project includes automated version checking and update capabilities:\n\n```bash\n# Check for Lucide version updates and artifact status\nmake check-lucide-version\n\n# Alternative: Use the CLI command directly\nuv run check-lucide-version\n```\n\n**Weekly Automation**: The repository automatically checks for new Lucide releases every Monday and creates update PRs when new versions are available.\n\n### Release Process\nThis project follows a manual release process:\n\n1. **Update version** in `pyproject.toml`:\n ```bash\n # Create release branch\n git checkout -b release/v0.2.0\n\n # Edit pyproject.toml to bump version\n # version = \"0.2.0\"\n\n # Commit and push\n git add pyproject.toml\n git commit -m \"Bump version to 0.2.0\"\n git push -u origin release/v0.2.0\n ```\n\n2. **Create and merge PR** for the version bump\n\n3. **Trigger publishing workflow**:\n - Go to [Actions](../../actions/workflows/publish.yml)\n - Click \"Run workflow\"\n - Select the main branch\n - Click \"Run workflow\"\n\n4. **Automatic publishing**: The `publish.yml` workflow builds and publishes the package to PyPI using trusted publishing.\n\n## How It Works\nThe package comes with a pre-built SQLite database containing all Lucide icons. When you call `lucide_icon()`, it fetches the icon's SVG from the database and applies your customizations. This approach means:\n- **Fast**: Icons are loaded from an efficient SQLite database\n- **Offline**: No internet connection required at runtime\n- **Customizable**: Build your own database with just the icons you need\n- **Maintainable**: Update to newer Lucide versions by rebuilding the database\n\n## License\nThis project is licensed under the MIT License - see the LICENSE file for details.\nThe Lucide icons themselves are also MIT licensed - see [Lucide's license](https://github.com/lucide-icons/lucide/blob/main/LICENSE).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for working with Lucide icons",
"version": "0.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/mmacpherson/python-lucide/issues",
"Homepage": "https://github.com/mmacpherson/python-lucide",
"Source Code": "https://github.com/mmacpherson/python-lucide"
},
"split_keywords": [
"lucide",
" icons",
" svg",
" sqlite"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d600f4306a3b0f8901320b264234629d8d89e1b8f8d43e82a4e98977fc630276",
"md5": "5e73363b4ec9b76cfd3a421e59c1b79d",
"sha256": "b964837766d460fc1df3f9fbf72d27b9fa284383be045dddd54f5582793435fd"
},
"downloads": -1,
"filename": "python_lucide-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5e73363b4ec9b76cfd3a421e59c1b79d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 147300,
"upload_time": "2025-07-28T17:41:25",
"upload_time_iso_8601": "2025-07-28T17:41:25.933509Z",
"url": "https://files.pythonhosted.org/packages/d6/00/f4306a3b0f8901320b264234629d8d89e1b8f8d43e82a4e98977fc630276/python_lucide-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "49201e0bf2a1bffc8a49939d8b40550919862df88e4d5bbfa749cb3cab8383e0",
"md5": "c6dc81a762ff8abeedd53627a46bfb18",
"sha256": "a7d18447960ce4fc30852836f44af915c99746c38d54866dd6c09802e7f1bbd9"
},
"downloads": -1,
"filename": "python_lucide-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "c6dc81a762ff8abeedd53627a46bfb18",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 151954,
"upload_time": "2025-07-28T17:41:26",
"upload_time_iso_8601": "2025-07-28T17:41:26.854916Z",
"url": "https://files.pythonhosted.org/packages/49/20/1e0bf2a1bffc8a49939d8b40550919862df88e4d5bbfa749cb3cab8383e0/python_lucide-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 17:41:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mmacpherson",
"github_project": "python-lucide",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "python-lucide"
}
