{"id":48856291,"url":"https://github.com/frank-895/docxblocks","last_synced_at":"2026-04-15T12:44:28.005Z","repository":{"id":301159796,"uuid":"1008343816","full_name":"frank-895/docxblocks","owner":"frank-895","description":"High-level, block-based abstraction for python-docx.","archived":false,"fork":false,"pushed_at":"2025-06-29T18:33:03.000Z","size":278,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T12:44:26.844Z","etag":null,"topics":["automation","document-generation","docx","open-source","python","python-docx","reporting","template-engine","word"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/docxblocks/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frank-895.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-25T11:56:01.000Z","updated_at":"2025-06-29T18:32:44.000Z","dependencies_parsed_at":"2025-06-25T13:30:05.633Z","dependency_job_id":null,"html_url":"https://github.com/frank-895/docxblocks","commit_stats":null,"previous_names":["frank-895/docxblocks"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/frank-895/docxblocks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frank-895%2Fdocxblocks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frank-895%2Fdocxblocks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frank-895%2Fdocxblocks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frank-895%2Fdocxblocks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frank-895","download_url":"https://codeload.github.com/frank-895/docxblocks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frank-895%2Fdocxblocks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31842193,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T11:29:19.690Z","status":"ssl_error","status_checked_at":"2026-04-15T11:29:19.171Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","document-generation","docx","open-source","python","python-docx","reporting","template-engine","word"],"created_at":"2026-04-15T12:44:27.152Z","updated_at":"2026-04-15T12:44:27.993Z","avatar_url":"https://github.com/frank-895.png","language":"Python","readme":"# DocxBlocks\n\nA Python library for building Word documents using a block-based API. Create complex documents with simple, readable code.\n\n## 🚀 Quick Start\n\n```python\nfrom docxblocks import DocxBuilder\n\n# Create blocks\nblocks = [\n    {\"type\": \"heading\", \"text\": \"Report Title\", \"level\": 1},\n    {\"type\": \"text\", \"text\": \"This is the first paragraph.\"},\n    {\"type\": \"text\", \"text\": \"This continues inline.\"},\n    {\"type\": \"text\", \"text\": \"\\nThis starts a new paragraph.\"},\n    {\"type\": \"table\", \"content\": {\n        \"headers\": [\"Name\", \"Value\"],\n        \"rows\": [[\"Item 1\", \"100\"], [\"Item 2\", \"200\"]]\n    }}\n]\n\n# Build document\nbuilder = DocxBuilder(\"template.docx\")\nbuilder.insert(\"{{content}}\", blocks)\nbuilder.save(\"output.docx\")\n```\n\n## 📋 Features\n\n- **Block-based API**: Each piece of content is a simple dictionary\n- **Smart text grouping**: Consecutive text blocks are grouped inline\n- **Simple newlines**: Every `\\n` creates a new paragraph\n- **Rich styling**: Bold, italic, colors, alignment, and more\n- **Table support**: Headers, rows, column widths, cell styling\n- **Image handling**: Automatic sizing with DPI calculation\n- **Template support**: Use existing Word templates as starting points\n- **Error handling**: Graceful fallbacks for missing content\n\n## 📖 Installation\n\n```bash\npip install docxblocks\n```\n\n## 🎯 Basic Usage\n\n### Template Setup\n\nCreate a Word document with placeholders:\n\n```\n{{header}}\n\n{{main}}\n\n{{footer}}\n```\n\n### Block-Based API (Core Concept)\n\nEach piece of content is a block:\n\n```python\n{\n  \"type\": \"text\",\n  \"text\": \"All systems operational.\",\n  \"style\": {\n    \"bold\": True,\n    \"italic\": False,\n    \"font_color\": \"007700\",\n    \"align\": \"center\",\n    \"style\": \"Normal\"\n  }\n}\n```\n\n### Text Block Behavior\n\nText blocks have simple, predictable behavior:\n\n- **Every `\\n`**: Always starts a new paragraph\n- **Inline grouping**: Consecutive text blocks without `\\n` are grouped together\n- **`spacing`**: Adds extra blank paragraphs after the block\n\n```python\n{\"type\": \"text\", \"text\": \"Line 1\\nLine 2\\nLine 3\"}\n# Renders as three paragraphs: Line 1, Line 2, Line 3\n\n{\"type\": \"text\", \"text\": \"First paragraph\\n\\nSecond paragraph\"}\n# Renders as: First paragraph, [blank paragraph], Second paragraph\n\n{\"type\": \"text\", \"text\": \"First\", \"spacing\": 1}\n# Renders as a new paragraph, then one blank paragraph after\n```\n\n### Table Cell Behavior\n\nTable cells and headers follow the same rules:\n\n- **Every `\\n`**: Always starts a new paragraph within the cell\n- **Inline grouping**: Consecutive cell blocks without `\\n` are grouped together\n\n```python\n{\n    \"type\": \"table\",\n    \"content\": {\n        \"headers\": [\"Name\", \"Description\\nDetails\"],\n        \"rows\": [\n            [\"Item 1\", \"First paragraph.\\nSecond paragraph.\"],\n            [\"Item 2\", \"Line 1\\n\\nLine 2 with empty line above\"]\n        ]\n    }\n}\n# Each '\\n' creates a new paragraph, each '\\n\\n' creates paragraph with empty line before\n```\n\nBlock types:\n\n| Type         | Required Keys     | Optional Keys     |\n|--------------|-------------------|-------------------|\n| `text`       | `text`            | `style`, `spacing`| \n| `heading`    | `text`, `level`   | `style`           |\n| `bullets`    | `items`           | `style`           |\n| `table`      | `content`         | `style`           |\n| `image`      | `path`            | `style`           |\n| `page_break` | -                 | -                 |\n| `header`     | `content`         | `apply_to`        |\n| `footer`     | `content`         | `apply_to`        |\n\n## 🎨 Styling\n\n### Text Styling\n```python\n{\n    \"type\": \"text\",\n    \"text\": \"Styled text\",\n    \"style\": {\n        \"bold\": True,\n        \"italic\": False,\n        \"font_color\": \"FF0000\",  # Red\n        \"align\": \"center\",       # \"left\", \"center\", \"right\", \"justify\"\n        \"style\": \"Normal\"\n    }\n}\n```\n\n### Alignment Options\nAll block types support four alignment options:\n```python\n# Text alignment examples\n{\"type\": \"text\", \"text\": \"Left aligned\", \"style\": {\"align\": \"left\"}}\n{\"type\": \"text\", \"text\": \"Centered text\", \"style\": {\"align\": \"center\"}}\n{\"type\": \"text\", \"text\": \"Right aligned\", \"style\": {\"align\": \"right\"}}\n{\"type\": \"text\", \"text\": \"Justified text that adjusts spacing for clean edges\", \"style\": {\"align\": \"justify\"}}\n\n# Works with all block types\n{\"type\": \"heading\", \"text\": \"Centered Heading\", \"level\": 1, \"style\": {\"align\": \"center\"}}\n{\"type\": \"bullets\", \"items\": [\"Item 1\", \"Item 2\"], \"style\": {\"align\": \"right\"}}\n```\n\n### Table Styling\n```python\n{\n    \"type\": \"table\",\n    \"content\": {\"headers\": [\"A\", \"B\"], \"rows\": [[\"1\", \"2\"]]},\n    \"style\": {\n        \"column_widths\": [0.3, 0.7],\n        \"header_styles\": {\"bold\": True, \"bg_color\": \"f2f2f2\"},\n        \"column_styles\": {0: {\"font_color\": \"FF0000\"}}\n    }\n}\n```\n\n**Rich Content in Cells:** Table cells can contain text, images, bullets, and headings. See [STYLEGUIDE.md](STYLEGUIDE.md) for examples.\n\n### Image Styling\n```python\n{\n    \"type\": \"image\",\n    \"path\": \"logo.png\",\n    \"style\": {\n        \"max_width\": \"4in\",\n        \"max_height\": \"300px\",\n        \"wrap_text\": \"square\",\n        \"horizontal_align\": \"left\",\n        \"vertical_align\": \"top\",\n        \"distance_from_text\": \"0.1in\"\n    }\n}\n```\n\n**Text Wrapping Options:** `inline`, `square`, `tight`, `through`, `top_and_bottom`, `behind`, `in_front`\n\n**Positioning:** `horizontal_align` (left/center/right), `vertical_align` (top/middle/bottom), `distance_from_text`\n\nSee [STYLEGUIDE.md](STYLEGUIDE.md) for comprehensive styling examples.\n\n## 📄 Headers and Footers\n\nDocxBlocks supports customizable headers and footers that can contain any combination of supported block types.\n\n### Basic Usage\n```python\nblocks = [\n    {\n        \"type\": \"header\",\n        \"apply_to\": \"all\",\n        \"content\": [\n            {\n                \"type\": \"text\",\n                \"text\": \"Company Name\\tDocument Title\\tPage {{page}}\",\n                \"style\": {\"align\": \"center\", \"font_color\": \"666666\"}\n            }\n        ]\n    },\n    {\n        \"type\": \"footer\", \n        \"apply_to\": \"all_except_first\",\n        \"content\": [\n            {\n                \"type\": \"text\",\n                \"text\": \"© 2024 Company. All rights reserved.\",\n                \"style\": {\"align\": \"center\", \"italic\": True}\n            }\n        ]\n    }\n]\n```\n\n**Apply To Options:** `\"all\"`, `\"all_except_first\"`, `\"first\"`, `\"odd\"`, `\"even\"`\n\nSee [STYLEGUIDE.md](STYLEGUIDE.md) for advanced examples including images and tables in headers/footers.\n\n## 🔧 Advanced Features\n\n### Mixed Content\n```python\nblocks = [\n    {\"type\": \"heading\", \"text\": \"Section 1\", \"level\": 2},\n    {\"type\": \"text\", \"text\": \"Introduction \"},\n    {\"type\": \"text\", \"text\": \"with \", \"style\": {\"bold\": True}},\n    {\"type\": \"text\", \"text\": \"inline styling.\"},\n    {\"type\": \"bullets\", \"items\": [\"Point 1\", \"Point 2\"]},\n    {\"type\": \"table\", \"content\": {...}},\n    {\"type\": \"page_break\"},\n    {\"type\": \"heading\", \"text\": \"Section 2\", \"level\": 2}\n]\n```\n\n### Template Variables\n```python\n# Template.docx contains: \"Hello {{name}}, here is your {{report_type}} report.\"\n\nbuilder = DocxBuilder(\"template.docx\")\nbuilder.insert(\"{{name}}\", [{\"type\": \"text\", \"text\": \"John\"}])\nbuilder.insert(\"{{report_type}}\", [{\"type\": \"text\", \"text\": \"monthly\"}])\nbuilder.save(\"output.docx\")\n```\n\n## 📚 Examples\n\nSee the `examples/` directory for complete working examples:\n\n- `text_block_example.py` - Basic text blocks and styling\n- `table_block_example.py` - Table creation and styling\n- `header_footer_example.py` - Headers and footers with various configurations\n- `all_except_first_example.py` - Cover page example with clean first page and headers on content pages\n- `newline_example.py` - Newline handling and paragraph behavior\n- `inline_text_example.py` - Inline text grouping\n- `alignment_example.py` - Text alignment with left, center, right, and justify\n- `combined_example.py` - Mixed block types\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 🐛 Issues\n\nFound a bug? Have a feature request? Please open an issue on GitHub.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrank-895%2Fdocxblocks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrank-895%2Fdocxblocks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrank-895%2Fdocxblocks/lists"}