html2pic 0.1.1__tar.gz

html2pic-0.1.1/.gitignore

@@ -0,0 +1,145 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

html2pic-0.1.1/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to html2pic will be documented in this file.
+
+## [0.1.1] - 2024-09-12
+
+### ✨ New Features
+- **Linear Gradient Support**: Added full support for CSS `linear-gradient()` in backgrounds
+  - Angle-based gradients: `linear-gradient(135deg, #667eea, #764ba2)`
+  - Keyword directions: `linear-gradient(to right, red, blue)`
+  - Color stops with percentages: `linear-gradient(90deg, red 0%, blue 100%)`
+  - Multiple colors with automatic distribution
+  - Support for all CSS color formats (hex, rgb, rgba, named colors)
+
+### 🔧 Improvements
+- Updated documentation with linear-gradient examples and limitations
+- Enhanced background rendering system to handle both images and gradients
+- Improved CSS parser to recognize linear-gradient as supported feature
+
+### 📝 Documentation
+- Added comprehensive linear-gradient documentation to README
+- Updated examples to showcase gradient capabilities
+- Clarified that only linear gradients are supported (radial/conic not yet implemented)
+
+## [0.1.0] - 2024-09-12
+
+### Initial Release
+
+#### ✨ Core Features
+- **HTML to Image Conversion**: Convert HTML + CSS to high-quality images using PicTex as rendering engine
+- **Modern CSS Layout**: Full flexbox support with `display: flex`, `justify-content`, `align-items`, `gap`, etc.
+- **Rich Typography**: Font families, sizes, weights, colors, text decorations, text shadows
+- **Complete Box Model**: Padding, margins, borders, border-radius support
+- **Visual Effects**: Box shadows and text shadows with RGBA color support
+- **Positioning**: Absolute positioning with `left` and `top` properties
+- **Background Images & Gradients**: Support for `background-image` with `url()` syntax and `linear-gradient()`, plus `background-size` (cover, contain, tile)
+
+#### 🏗️ Architecture
+- **Modular Design**: Clean separation of HTML parser, CSS parser, style engine, and translator
+- **Comprehensive Warnings System**: Detailed debugging information for unsupported features
+- **CSS Cascade Engine**: Proper specificity calculations and inheritance
+- **Smart Translation**: Maps HTML/CSS concepts to PicTex builders (Canvas, Row, Column, Text, Image)
+
+#### 📋 Supported HTML Elements
+- Container elements: `div`, `section`, `article`, `header`, `footer`, `main`, `nav`, `aside`
+- Text elements: `h1`-`h6`, `p`, `span`, `strong`, `em`, `b`, `i`, `u`, `s`
+- Media elements: `img`
+- List elements: `ul`, `ol`, `li`
+- Other: `a`, `br`, `hr`
+
+#### 🎨 Supported CSS Features
+- **Layout**: `display` (flex, block, inline), `flex-direction`, `justify-content`, `align-items`, `gap`
+- **Box Model**: `width`, `height`, `padding`, `margin`, `border`, `border-radius`
+- **Typography**: `font-family`, `font-size`, `font-weight`, `font-style`, `color`, `text-align`, `line-height`, `text-decoration`
+- **Visual Effects**: `background-color`, `background-image`, `background-size`, `box-shadow`, `text-shadow`
+- **Positioning**: `position: absolute` with `left` and `top`
+- **Units**: `px`, `em`, `rem`, `%` support
+- **Colors**: Hex, RGB, RGBA, and named colors
+
+#### 🚨 Intelligent Warnings System
+- **CSS Validation**: Warns about unexpected/invalid CSS property values
+- **HTML Element Detection**: Warns about unrecognized or unsupported HTML elements
+- **Feature Limitations**: Clear warnings about unsupported CSS features with alternatives
+- **Color Fallbacks**: Automatic fallback for invalid colors with warnings
+- **Categorized Warnings**: Organized by HTML parsing, CSS parsing, style application, etc.
+
+#### 🔧 Developer Experience
+- **Simple API**: Clean `Html2Pic(html, css).render()` interface
+- **Multiple Output Formats**: PNG, JPG via PicTex integration
+- **Debug Information**: `get_warnings()`, `print_warnings()`, `get_warnings_summary()` methods
+- **Error Handling**: Graceful degradation with informative warnings instead of crashes
+
+#### 🏃‍♂️ Performance Features
+- **Empty Element Optimization**: Only renders elements with visual styles
+- **Smart RGBA Parsing**: Proper handling of RGBA colors in shadows and backgrounds
+- **Efficient Shadow Parsing**: Supports multiple shadows on single elements
+
+#### 🌟 Special Improvements
+- **Fixed Empty Div Rendering**: Empty divs with visual styles (background, borders, shadows) now render correctly
+- **Advanced Shadow Support**: Full CSS shadow syntax with multiple shadows and RGBA colors
+- **Background Image Integration**: Complete CSS background-image support with PicTex backend
+- **Comprehensive Property Validation**: Validates CSS values and provides helpful error messages
+
+### Known Limitations
+- CSS Grid layout not supported (use Flexbox instead)
+- Relative positioning not supported (use absolute positioning)
+- CSS transforms and animations not supported
+- Background gradients not supported (use solid colors or images)
+- Complex selectors (descendants, pseudo-classes) not supported
+
+### Dependencies
+- PicTex: High-quality rendering engine
+- BeautifulSoup4: HTML parsing
+- tinycss2: CSS parsing
+
+---
+
+*This project was developed using AI assistance (Claude Code) for rapid prototyping and implementation.*

html2pic-0.1.1/PKG-INFO

@@ -0,0 +1,347 @@
+Metadata-Version: 2.4
+Name: html2pic
+Version: 0.1.1
+Summary: Convert HTML + CSS to images without a browser
+Project-URL: Homepage, https://github.com/francozanardi/html2pic
+Project-URL: Repository, https://github.com/francozanardi/html2pic.git
+Project-URL: Bug Tracker, https://github.com/francozanardi/html2pic/issues
+Project-URL: Documentation, https://github.com/francozanardi/html2pic/blob/main/README.md
+Project-URL: Examples, https://github.com/francozanardi/html2pic/tree/main/examples
+Author-email: Franco Zanardi <francozanardi97@gmail.com>
+License-Expression: MIT
+Keywords: conversion,css,html,image,rendering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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 :: Graphics Conversion
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.8
+Requires-Dist: beautifulsoup4>=4.9.0
+Requires-Dist: pictex
+Requires-Dist: tinycss2>=1.1.0
+Provides-Extra: examples
+Requires-Dist: pillow>=8.0.0; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# html2pic
+
+**Convert HTML + CSS to beautiful images using PicTex**
+
+`html2pic` is a Python library that translates a subset of HTML and CSS to high-quality images without requiring a browser engine. Built on top of [PicTex](https://github.com/francozanardi/pictex), it provides a powerful and intuitive way to generate images from web markup.
+
+## ⚠️ **Experimental Software Notice**
+
+**This is experimental software developed primarily using AI assistance (Claude Code).** While functional, it should be used with caution in production environments. Key considerations:
+
+- **Rapid Development**: Most of the codebase was generated and refined through AI-assisted programming
+- **Limited Testing**: Extensive testing in diverse environments is still ongoing  
+- **Active Development**: APIs and behavior may change significantly in future versions
+- **Community Feedback Welcome**: Please report issues and suggest improvements via GitHub
+
+Use this library for prototyping, experimentation, and non-critical applications. For production use, thorough testing is recommended.
+
+## 🚀 Key Features
+
+- **No Browser Required**: Pure Python implementation using PicTex as the rendering engine
+- **Flexbox Support**: Modern CSS layout with `display: flex`, `justify-content`, `align-items`, etc.
+- **Rich Typography**: Font families, sizes, weights, colors, and text decorations
+- **Box Model**: Complete support for padding, margins, borders, and border-radius  
+- **Responsive Sizing**: Supports px, em, rem, % units and flexible sizing modes
+- **High Quality Output**: Vector (SVG) and raster (PNG, JPG) output formats
+- **Simple API**: Clean, intuitive interface inspired by modern web development
+
+## 📦 Installation
+
+```bash
+pip install html2pic
+```
+
+## 🎯 Quick Start
+
+```python
+from html2pic import Html2Pic
+
+# Your HTML content
+html = '''
+<div class="card">
+    <h1>Hello, World!</h1>
+    <p class="subtitle">Generated with html2pic</p>
+</div>
+'''
+
+# Your CSS styles
+css = '''
+.card {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    padding: 30px;
+    background-color: #f0f8ff;
+    border-radius: 15px;
+    width: 300px;
+}
+
+h1 {
+    color: #2c3e50;
+    font-size: 28px;
+    margin: 0 0 10px 0;
+}
+
+.subtitle {
+    color: #7f8c8d;
+    font-size: 16px;
+    margin: 0;
+}
+'''
+
+# Create and render
+renderer = Html2Pic(html, css)
+image = renderer.render()
+image.save("output.png")
+```
+
+## 🏗️ Architecture
+
+html2pic works by translating HTML + CSS concepts to PicTex builders:
+
+1. **HTML Parser**: Uses BeautifulSoup to create a DOM tree
+2. **CSS Parser**: Uses tinycss2 to extract style rules  
+3. **Style Engine**: Applies CSS cascade, specificity, and inheritance
+4. **Translator**: Maps styled DOM nodes to PicTex builders (Canvas, Row, Column, Text, Image)
+5. **Renderer**: Uses PicTex to generate the final image
+
+## 📋 Supported HTML/CSS Features
+
+### HTML Elements
+- `<div>`, `<section>`, `<article>` → Layout containers
+- `<h1>`-`<h6>`, `<p>`, `<span>` → Text elements
+- `<img>` → Image elements
+
+### CSS Layout
+- `display: flex` with `flex-direction: row|column`
+- `justify-content`: `flex-start`, `center`, `flex-end`, `space-between`, `space-around`, `space-evenly`
+- `align-items`: `flex-start`, `center`, `flex-end`, `stretch`
+- `gap` for spacing between flex items
+
+### CSS Box Model  
+- `width`, `height` (px, %, auto, fit-content, fill-available)
+- `padding`, `margin` (shorthand and individual sides)
+- `border` with width, style (solid, dashed, dotted), and color
+- `border-radius` (px and %)
+- `background-color` (solid colors and linear gradients)
+- `background-image` (url() and linear-gradient())
+- `background-size` (cover, contain, tile for images)
+- `box-shadow` (offset-x, offset-y, blur-radius, color)
+
+### CSS Typography
+- `font-family`, `font-size`, `font-weight`, `font-style`
+- `color`, `text-align`, `line-height`
+- `text-decoration` (underline, line-through)
+- `text-shadow` (offset-x, offset-y, blur-radius, color)
+
+#### Font Loading
+html2pic supports loading fonts from the system or custom font files:
+
+```css
+/* System font */
+font-family: "Arial", sans-serif;
+
+/* Custom font file (provide absolute path) */
+font-family: "/path/to/custom-font.ttf";
+
+/* Multiple fallbacks */
+font-family: "Custom Font", "Arial", sans-serif;
+```
+
+**Note**: When using custom fonts, provide the full path to the font file (.ttf, .otf). If the font cannot be loaded, it will fall back to system defaults.
+
+#### Linear Gradients
+html2pic supports CSS linear-gradient syntax for backgrounds:
+
+```css
+/* Angle-based gradients */
+background-image: linear-gradient(135deg, #667eea, #764ba2);
+
+/* Direction keywords */  
+background-image: linear-gradient(to right, red, blue);
+
+/* Color stops with percentages */
+background-image: linear-gradient(90deg, #ff0000 0%, #00ff00 50%, #0000ff 100%);
+
+/* Multiple colors */
+background-image: linear-gradient(45deg, yellow, orange, red, purple);
+```
+
+**Supported features:**
+- Angle directions (0deg, 45deg, 135deg, etc.)
+- Keyword directions (to right, to bottom, to top left, etc.)  
+- Color stops with percentages
+- Multiple colors with automatic distribution
+- All CSS color formats (hex, rgb, rgba, named colors)
+
+**Limitations**: Only linear gradients are supported. Radial and conic gradients are not yet implemented.
+
+### CSS Positioning
+- `position: absolute` with `left` and `top` properties (px, %, em, rem)
+- **Limitation**: Only `left` and `top` are supported, not `right` or `bottom`
+
+### CSS Selectors
+- Tag selectors: `div`, `p`, `h1`
+- Class selectors: `.my-class`  
+- ID selectors: `#my-id`
+- Universal selector: `*`
+
+## 📝 Examples
+
+Explore the `examples/` folder for complete runnable examples with generated output images.
+
+### Quick Start Example
+Basic card layout demonstrating core html2pic functionality:
+
+```python
+from html2pic import Html2Pic
+
+html = '''
+<div class="card">
+    <h1>Hello, World!</h1>
+    <p class="subtitle">Generated with html2pic</p>
+</div>
+'''
+
+css = '''
+.card {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    padding: 30px;
+    background-color: #f0f8ff;
+    border-radius: 15px;
+    width: 300px;
+}
+
+h1 {
+    color: #2c3e50;
+    font-size: 28px;
+    margin: 0 0 10px 0;
+}
+
+.subtitle {
+    color: #7f8c8d;
+    font-size: 16px;
+    margin: 0;
+}
+'''
+
+renderer = Html2Pic(html, css)
+image = renderer.render()
+image.save("output.png")
+```
+
+![Quick Start Result](examples/01_quick_start_output.png)
+
+### Flexbox Card Layout
+Social media style user card with horizontal layout:
+
+```python
+html = '''
+<div class="user-card">
+    <div class="avatar"></div>
+    <div class="user-info">
+        <h2>Alex Doe</h2>
+        <p>@alexdoe</p>
+    </div>
+</div>
+'''
+
+css = '''
+.user-card {
+    display: flex;
+    align-items: center;
+    gap: 15px;
+    padding: 20px;
+    background-color: white;
+    border-radius: 12px;
+    border: 1px solid #e1e8ed;
+}
+
+.avatar {
+    width: 60px;
+    height: 60px;
+    background-color: #1da1f2;
+    border-radius: 50%;
+}
+
+.user-info h2 {
+    margin: 0 0 4px 0;
+    font-size: 18px;
+    color: #14171a;
+}
+
+.user-info p {
+    margin: 0;
+    color: #657786;
+    font-size: 14px;
+}
+'''
+```
+
+![Flexbox Card Result](examples/02_flexbox_card_output.png)
+
+### Advanced Visual Effects
+Shadows, positioning, and advanced styling features:
+
+![Shadows and Effects Result](examples/04_shadows_and_effects_output.png)
+
+### Background Images  
+Background image support with different sizing modes:
+
+![Background Images Result](examples/05_background_images_output.png)
+
+**Complete examples** with full source code are available in the [`examples/`](examples/) directory.
+
+## 🔧 API Reference
+
+### Html2Pic Class
+
+```python
+Html2Pic(html: str, css: str = "", base_font_size: int = 16)
+```
+
+**Methods:**
+- `render(crop_mode=CropMode.SMART) -> BitmapImage`: Render to raster image
+- `render_as_svg(embed_font=True) -> VectorImage`: Render to SVG
+- `debug_info() -> dict`: Get debugging information about parsing and styling
+
+### Output Objects
+
+The rendered images are PicTex `BitmapImage` or `VectorImage` objects with methods like:
+- `save(filename)`: Save to file
+- `to_numpy()`: Convert to NumPy array  
+- `to_pillow()`: Convert to PIL Image
+- `show()`: Display the image
+
+## 🚧 Current Limitations  
+
+This is an early version focusing on core functionality. A lot of features are not yet supported.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built on top of [PicTex](https://github.com/your-pictex-repo) for high-quality rendering
+- Uses [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/) for HTML parsing  
+- Uses [tinycss2](https://github.com/Kozea/tinycss2) for CSS parsing