html2pic 0.1.1__py3-none-any.whl

html2pic/warnings_system.py

@@ -0,0 +1,192 @@
+"""
+Warning system for html2pic - provides detailed debugging information
+"""
+
+import warnings
+from typing import List, Dict, Any, Optional
+from enum import Enum
+
+class WarningCategory(Enum):
+    """Categories of warnings for better organization"""
+    HTML_PARSING = "html_parsing"
+    CSS_PARSING = "css_parsing" 
+    STYLE_APPLICATION = "style_application"
+    TRANSLATION = "translation"
+    RENDERING = "rendering"
+    UNSUPPORTED_FEATURE = "unsupported_feature"
+
+class Html2PicWarning(UserWarning):
+    """Base warning class for html2pic"""
+    pass
+
+class UnsupportedFeatureWarning(Html2PicWarning):
+    """Warning for unsupported HTML/CSS features"""
+    pass
+
+class StyleApplicationWarning(Html2PicWarning):
+    """Warning for style application issues"""
+    pass
+
+class TranslationWarning(Html2PicWarning):
+    """Warning for DOM to PicTex translation issues"""
+    pass
+
+class ParsingWarning(Html2PicWarning):
+    """Warning for HTML/CSS parsing issues"""
+    pass
+
+class WarningCollector:
+    """
+    Collects and manages warnings during the html2pic conversion process.
+    
+    This provides a centralized way to track all issues that occur during
+    HTML/CSS parsing, style application, and rendering.
+    """
+    
+    def __init__(self):
+        self.warnings: List[Dict[str, Any]] = []
+        self._enabled = True
+    
+    def warn(self, message: str, category: WarningCategory, details: Optional[Dict[str, Any]] = None, 
+             warning_class: type = Html2PicWarning):
+        """
+        Add a warning with detailed context information.
+        
+        Args:
+            message: Human-readable warning message
+            category: Category of the warning
+            details: Additional context (element info, CSS rule, etc.)
+            warning_class: Specific warning class to use
+        """
+        if not self._enabled:
+            return
+        
+        warning_info = {
+            'message': message,
+            'category': category.value,
+            'details': details or {},
+            'warning_class': warning_class.__name__
+        }
+        
+        self.warnings.append(warning_info)
+        
+        # Also emit a standard Python warning
+        warnings.warn(f"[{category.value.upper()}] {message}", warning_class, stacklevel=3)
+    
+    def warn_unsupported_html_tag(self, tag_name: str, context: str = ""):
+        """Warn about unsupported HTML tags"""
+        self.warn(
+            f"HTML tag '<{tag_name}>' is not supported and was skipped",
+            WarningCategory.HTML_PARSING,
+            {'tag': tag_name, 'context': context},
+            UnsupportedFeatureWarning
+        )
+    
+    def warn_unsupported_css_property(self, property_name: str, value: str, selector: str = ""):
+        """Warn about unsupported CSS properties"""
+        self.warn(
+            f"CSS property '{property_name}: {value}' is not supported",
+            WarningCategory.CSS_PARSING,
+            {'property': property_name, 'value': value, 'selector': selector},
+            UnsupportedFeatureWarning
+        )
+    
+    def warn_css_selector_ignored(self, selector: str, reason: str):
+        """Warn about CSS selectors that were ignored"""
+        self.warn(
+            f"CSS selector '{selector}' was ignored: {reason}",
+            WarningCategory.CSS_PARSING,
+            {'selector': selector, 'reason': reason},
+            ParsingWarning
+        )
+    
+    def warn_style_not_applied(self, property_name: str, value: str, element_info: str, reason: str):
+        """Warn about styles that couldn't be applied"""
+        self.warn(
+            f"Style '{property_name}: {value}' could not be applied to {element_info}: {reason}",
+            WarningCategory.STYLE_APPLICATION,
+            {'property': property_name, 'value': value, 'element': element_info, 'reason': reason},
+            StyleApplicationWarning
+        )
+    
+    def warn_element_skipped(self, element_info: str, reason: str):
+        """Warn about elements that were skipped during translation"""
+        self.warn(
+            f"Element {element_info} was skipped: {reason}",
+            WarningCategory.TRANSLATION,
+            {'element': element_info, 'reason': reason},
+            TranslationWarning
+        )
+    
+    def warn_color_fallback(self, original_color: str, fallback_color: str, reason: str):
+        """Warn about color values that fell back to defaults"""
+        self.warn(
+            f"Color '{original_color}' fell back to '{fallback_color}': {reason}",
+            WarningCategory.STYLE_APPLICATION,
+            {'original': original_color, 'fallback': fallback_color, 'reason': reason},
+            StyleApplicationWarning
+        )
+    
+    def get_warnings(self, category: Optional[WarningCategory] = None) -> List[Dict[str, Any]]:
+        """Get all warnings, optionally filtered by category"""
+        if category is None:
+            return self.warnings.copy()
+        return [w for w in self.warnings if w['category'] == category.value]
+    
+    def get_summary(self) -> Dict[str, Any]:
+        """Get a summary of all warnings"""
+        by_category = {}
+        for warning in self.warnings:
+            cat = warning['category']
+            if cat not in by_category:
+                by_category[cat] = []
+            by_category[cat].append(warning)
+        
+        return {
+            'total_warnings': len(self.warnings),
+            'by_category': {cat: len(warnings) for cat, warnings in by_category.items()},
+            'categories': by_category
+        }
+    
+    def print_summary(self):
+        """Print a formatted summary of warnings"""
+        if not self.warnings:
+            print("✅ No warnings - conversion completed successfully!")
+            return
+        
+        summary = self.get_summary()
+        print(f"\n⚠️  Conversion completed with {summary['total_warnings']} warnings:")
+        
+        for category, count in summary['by_category'].items():
+            print(f"  {category.replace('_', ' ').title()}: {count}")
+        
+        print("\nDetailed warnings:")
+        for i, warning in enumerate(self.warnings, 1):
+            print(f"  {i}. [{warning['category'].upper()}] {warning['message']}")
+            if warning['details']:
+                for key, value in warning['details'].items():
+                    print(f"     {key}: {value}")
+    
+    def clear(self):
+        """Clear all collected warnings"""
+        self.warnings.clear()
+    
+    def enable(self):
+        """Enable warning collection"""
+        self._enabled = True
+    
+    def disable(self):
+        """Disable warning collection"""
+        self._enabled = False
+
+# Global warning collector instance
+_global_collector = WarningCollector()
+
+def get_warning_collector() -> WarningCollector:
+    """Get the global warning collector instance"""
+    return _global_collector
+
+def reset_warnings():
+    """Reset the global warning collector"""
+    global _global_collector
+    _global_collector.clear()

html2pic-0.1.1.dist-info/METADATA

@@ -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

html2pic-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+html2pic/__init__.py,sha256=E1yV95IM2tTDTNgJO97vWxy5a_Aml_TsJrJd4yUW0bA,1169
+html2pic/core.py,sha256=BUmxV6L3MmCMFs2BMVYWyXWyaPe4OTg0pcbzG2Cy62Y,6517
+html2pic/css_parser.py,sha256=nJoKRCaopGGAazH5w-MGq6Z5Dm0ohKpAaWH-xo6X5LU,11355
+html2pic/exceptions.py,sha256=UCTkyOaCQ13V5Rziz_aKN1XyLhyV5j3jS7_x94F46Iw,455
+html2pic/html_parser.py,sha256=zmZxVj4_2wPEDl8JNfqGrEFxL61Hp0T3m4HZXnLTVJA,6349
+html2pic/models.py,sha256=QPrLvN-lFxWS8D3uS_R3J2KLVJDK6mhwb55Idhxl9gQ,5492
+html2pic/style_engine.py,sha256=HgqX6es1cUUWFTC-LXfZJPKGhUVyQ6MrLDjlXO43cps,17630
+html2pic/translator.py,sha256=IM1YtiyOY878pvYhvfxkmYeq3eI87YLsgz1kEBGZp80,38195
+html2pic/warnings_system.py,sha256=3nxjmrrjUnmxk_7GgMVIUCCQJDgzS9Vr-bENfSigUPY,7158
+html2pic-0.1.1.dist-info/METADATA,sha256=eApxktFCOl5YiG-i_8dXyL8p9M_EBlLftkZqsC9MZAA,10491
+html2pic-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+html2pic-0.1.1.dist-info/RECORD,,

html2pic-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any