{"id":3469,"library":"dominate","title":"Dominate","description":"Dominate is a Python library (current version 2.9.1) for creating and manipulating HTML documents using an elegant DOM API. It allows developers to write HTML pages concisely in pure Python, eliminating the need for a separate template language. The library is actively maintained with a regular release cadence.","status":"active","version":"2.9.1","language":"en","source_language":"en","source_url":"https://github.com/Knio/dominate","tags":["html","dom","templating","web development","declarative ui"],"install":[{"cmd":"pip install dominate","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Used to create a full HTML document structure.","symbol":"document","correct":"from dominate.document import document"},{"note":"Commonly imported as 'tags' to access HTML elements like tags.html, tags.body, tags.h1, etc.","symbol":"tags","correct":"from dominate import tags"},{"note":"Direct import of specific tags for convenience.","symbol":"html","correct":"from dominate.tags import html, body, h1"},{"note":"Useful for inserting raw text that should not be further escaped or parsed as HTML.","symbol":"text","correct":"from dominate.util import text"}],"quickstart":{"code":"from dominate.document import document\nfrom dominate.tags import html, head, body, h1, p, a, div, br\nfrom dominate.util import text\n\ndoc = document(title='My Awesome Page')\n\nwith doc.head:\n    a(href='https://example.com', _class='link-style', data_info='example') << 'Example Link'\n\nwith doc.body:\n    h1('Hello, Dominate!')\n    p('This is a paragraph created with Python.')\n    with div(id='container'):\n        p('Another paragraph inside a div.')\n        p('Line one.')\n        br()\n        p('Line two with explicit break.')\n        p('Raw text with newline:\\n')\n        text('This text should appear on a new line after the explicit break.')\n\n# Render the document to an HTML string\nhtml_output = doc.render()\nprint(html_output)\n\n# Example of rendering with pretty printing off\n# print(doc.render(pretty=False))","lang":"python","description":"This quickstart demonstrates creating a basic HTML document, adding elements to the head and body, nesting elements using `with` statements, and adding attributes including custom data attributes. It also shows how to explicitly add line breaks and handle raw text, highlighting a common 'gotcha' with newlines."},"warnings":[{"fix":"Use `dominate.tags.br()` for explicit line breaks or wrap text in appropriate block-level elements like `p()`. For raw text that should not be escaped and contains newlines, consider inserting it with `dominate.util.text()` into a `<pre>` tag or similar.","message":"Newline characters (`\\n`) in Python strings are not automatically converted to HTML `<br>` tags when inserted into Dominate elements. You must explicitly add `<br/>` tags or use `dominate.util.text` if you intend for newlines to be preserved visually in the rendered HTML, or `p` tags for paragraphs.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Prefix Python reserved keywords used as HTML attributes with an underscore (e.g., `_class`, `_for`).","message":"When adding attributes to HTML tags, Python keywords (e.g., `class`, `for`) must be escaped with an underscore, like `_class='my-class'` or `_for='my-label'` to avoid syntax errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When using `dominate` within asynchronous code, ensure that any operations that might block the event loop are handled appropriately. If a `dominate` component is designed to be an `async` context manager or interact with `async` resources, ensure `await` is used correctly with `__aenter__` and `__aexit__` (though `dominate` itself does not inherently require `await` for its core DOM manipulation, new integrations might).","message":"Version 2.9.1 introduced support for `dominate` to work in async contexts. While this is an enhancement, improper use of `dominate` elements or context managers within `async` functions without awaiting where necessary could lead to unexpected behavior or runtime errors in `asyncio` applications.","severity":"breaking","affected_versions":">=2.9.1"},{"fix":"When using `with` statements, each `with` block implicitly adds created elements to the current context. If you intend to build up a single element incrementally, add content directly to its `.add()` method or `+=` operator, or ensure the instance is correctly managed within a single `with` context for its children.","message":"When reusing tag instances (e.g., creating a tag and then adding content to it multiple times in different contexts), be aware of Dominate's context management. If a tag instance is created outside a `with` block and then used inside multiple `with` blocks, its content might be duplicated or not appear where expected.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}