BREAKING CHANGE in tools.py - see changelog. bumped version to 0.1.16

Author: joeldodson

docs/CHANGELOG.md

@@ -1,16 +1,29 @@
 # Changelog
 
+## v0.1.16 (2025-03-27) -- BREAKING BACKWARD COMPATIBILITY  
+
+- BREAKING: Changed domible.tools.open_html_in_browser to open_html_document_in_browser
+- and added domible.tools.open_html_fragment_in_browser
+- makes it easier to, for example, create an HTML table using a builder then have that table popped open in the browser
+- updated domible.tools.open_object_in_browser
+
+  - this change is transpaerent but is good for testing open_html_fragment_in_browser
+
 ## v0.1.15 (2025-01-13) 
 
 - this version is motivated by a desire to toggle visibility of all details elements 
 - and now, forms... starting with the button  
+
   - this is a very basic ability to create a button element
   - any attributes (e.g., type) will be done manually or via a builders class
   - this is all TBD and might change in subsequent releases 
+
 - a new builder to add a toggle button to a page to expand/collapse the content of a details element 
+
   - this is also the introduction of JavaScript into domible (sorry, it was inevitable) 
   - the JS is hard coded into the builder, which might be the long term solution, but I doubt it 
   - focus is on functionality, no CSS has been added 
+
 - added toggle details button into efo.py in tests 
 - added a toggle details button in open_object_in_browser() in domible tools 
 - fixed bug in Script element where contents was not being passed to super().__init__ 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "domible"
-version = "0.1.15"
+version = "0.1.16"
 description = "python classes to create accessible HTML elements and documents "
 authors = ["Joel Dodson <joeldodson@gmail.com>"]
 maintainers = ["BlindGumption <blindgumption@gmail.com>"]

src/dicli/main.py

@@ -25,7 +25,7 @@
 from domible.elements import Heading, Anchor, Paragraph
 from domible.builders.tableBuilder import TableBuilder, build_table_from_dicts
 from domible.starterDocuments import basic_head_empty_body
-from domible.tools import open_html_in_browser
+from domible.tools import open_html_document_in_browser
 
 import argparse
 
@@ -51,7 +51,7 @@ def simple(args) -> None:
             ),
         ]
     )
-    open_html_in_browser(htmlDoc)
+    open_html_document_in_browser(htmlDoc)
 
 
 def elements(args) -> None:
@@ -94,7 +94,7 @@ def elements(args) -> None:
                 deprecatedTable,
             ]
         )
-    open_html_in_browser(htmlDoc)
+    open_html_document_in_browser(htmlDoc)
 
 
 def ctfd(args) -> None:
@@ -120,7 +120,7 @@ def ctfd(args) -> None:
             table,
         ]
     )
-    open_html_in_browser(htmlDoc)
+    open_html_document_in_browser(htmlDoc)
 
 
 def lists(args) -> None:
@@ -238,7 +238,7 @@ def lists(args) -> None:
             detailsList,
         ]
     )
-    open_html_in_browser(htmlDoc)
+    open_html_document_in_browser(htmlDoc)
 
 
 def list_builder(args) -> None:
@@ -247,7 +247,7 @@ def list_builder(args) -> None:
     htmlDoc = basic_head_empty_body(title)
     body = htmlDoc.get_body_element()
     body.add_content([])
-    open_html_in_browser(htmlDoc)
+    open_html_document_in_browser(htmlDoc)
 
 
 def headings(args) -> None:
@@ -302,7 +302,7 @@ def headings(args) -> None:
             contents="heading level 3 with 'somethingUnique' for unique",
         )
     )
-    open_html_in_browser(htmlDoc)
+    open_html_document_in_browser(htmlDoc)
 
 
 def run() -> None:

src/distarter/main.py

@@ -3,10 +3,11 @@
 this file serves as Python code to get started with domible
 """
 
+import domible
 from domible.elements import Html, Body, Title
 from domible.elements import Heading, Anchor, Paragraph, HorizontalRule 
 from domible.starterDocuments import basic_head_empty_body
-from domible.tools import open_html_in_browser
+from domible.tools import open_html_document_in_browser
 
 
 #######
@@ -19,16 +20,17 @@ def run() -> None:
     cib_anchor = Anchor(
         href="http://codinginblind.vip", contents="the Coding In Blind website"
     )
+    version = domible.__version__
     htmlDoc = basic_head_empty_body(title)
     body = htmlDoc.get_body_element()
     body.add_content([
-        Heading(1, title), 
+        Heading(1, title),
+        Paragraph(f"using domible version {version}"),
         Paragraph(f"check out: {cib_anchor}"),
         HorizontalRule(),
         Paragraph('Adding a non printable character, codepoint = 0xfeff, in the square brackets [\ufeff] to make sure encodings are set correctly.')
     ])
-    open_html_in_browser(htmlDoc)
-    ## open_html_in_browser(htmlDoc, "saved_distarter.html", True)
+    open_html_document_in_browser(htmlDoc)
 
 
 if __name__ == "__main__":

src/domible/__init__.py

@@ -8,5 +8,6 @@
 import domible.elements
 import domible.builders
 import domible.starterDocuments 
-from domible.tools import open_object_in_browser, open_html_in_browser, save_to_file 
+from domible.tools import open_object_in_browser, open_html_document_in_browser, save_to_file 
+
 ## end of file 

src/domible/tools.py

@@ -1,21 +1,21 @@
-""" domible/src/domible/tools.py
+"""domible/src/domible/tools.py
 
 tools.py has functions for users of the domible package to do simple things
 like open their HTML doc in the browser,
 or save the HTML to a specified file.
 tools.py imports other modules within domible thus should not be used by any of domible's submodules.
-Any helper functions needed by domible should be put in utils.py 
-See the top level comments in utils.py to understand why tools.py exists. 
+Any helper functions needed by domible should be put in utils.py
+See the top level comments in utils.py to understand why tools.py exists.
 """
 
-from pathlib import Path 
+from pathlib import Path
 from tempfile import NamedTemporaryFile
 import webbrowser as wb
 
-from domible.elements import BaseElement 
-from domible.elements import Html, Body, Heading 
-from domible.builders import element_from_object, default_toggle_details_button  
-from domible.starterDocuments import basic_head_empty_body 
+from domible.elements import BaseElement
+from domible.elements import Html, Body, Heading, Div
+from domible.builders import element_from_object, default_toggle_details_button
+from domible.starterDocuments import basic_head_empty_body
 
 
 def save_to_file(element: BaseElement, filename: str, force: bool = False) -> None:
@@ -37,39 +37,64 @@ def save_to_file(element: BaseElement, filename: str, force: bool = False) -> No
         f.write(f"{element}")
 
 
-def open_html_in_browser(html_doc: Html, save_file: str = None, force: bool = False) -> None:
+def open_html_document_in_browser(
+    html_doc: Html, save_file: str = None, force: bool = False
+) -> None:
     """
     open the html_doc in the default browser.
     if a save_to_file is provided, also save the html_doc to that file,
-    else use a temporary file 
+    else use a temporary file
     """
     if save_file:
         save_to_file(html_doc, save_file, force)
-        # path must be absolute to match how temp file works 
-        path = str(Path(save_file).absolute()) 
-    else: 
-        path =NamedTemporaryFile(delete=False, suffix='.html')
-        f=open(path.name, 'w+t', encoding='utf-8')
+        # path must be absolute to match how temp file works
+        path = str(Path(save_file).absolute())
+    else:
+        path = NamedTemporaryFile(delete=False, suffix=".html")
+        f = open(path.name, "w+t", encoding="utf-8")
         f.write(f"{html_doc}")
         f.close()
-        path = path.name # consistent with path from saving file 
-    wb.open('file://' + path)
+        path = path.name  # consistent with path from saving file
+    wb.open("file://" + path)
 
 
-def open_object_in_browser(obj: object, depth:int = 42, title: str = "opening an object in the browser", save_file: str = None, force: bool = False) -> None:
+def open_html_fragment_in_browser(
+    html_frag: BaseElement,
+    title: str = "opening HTML fragment",
+    save_file: str = None,
+    force: bool = False,
+) -> None:
     """
-    get HTML representation of the object then open it in the default browser.
+    open some bit of HTML you've created in the default browser,
+    using the default basic HTML doc.
+    This is useful if you have some HTML you want to view in a browser
+    and don't want to create the document and get the body and so on...
+    This is sort of analogous to open_object_in_browser
+    """
+    html_doc: Html = basic_head_empty_body(title)
+    body: Body = html_doc.get_body_element()
+    body.add_content(html_frag)
+
 
-    the passed in object is used to get HTML using element_from_object.
-    That HTML is then put into a simple HtML document using the basicHeadEmptyBody starter document.
-    that simple document is then opened in the browser. 
+def open_object_in_browser(
+    obj: object,
+    depth: int = 42,
+    title: str = "opening an object in the browser",
+    save_file: str = None,
+    force: bool = False,
+) -> None:
+    """
+    get HTML representation of the object then open it in the default browser.
     """
     obj_html = element_from_object(obj, depth)
-    html_doc: Html  = basic_head_empty_body(title)
-    body: Body = html_doc.get_body_element() 
-    body.add_content([Heading(1, f"showing object of type {type(obj).__name__}"), default_toggle_details_button()])
-    body.add_content(obj_html)
-    open_html_in_browser(html_doc, save_file, force)
+    frag: Div = Div(
+        [
+            Heading(1, f"showing object of type {type(obj).__name__}"),
+            default_toggle_details_button(),
+            obj_html,
+        ]
+    )
+    open_html_fragment_in_browser(frag, title, save_file, force)
 
 
 ## end of file

tests/efo.py

@@ -15,7 +15,7 @@
 from sys import argv
 
 from domible.builders import element_from_object, ToggleDetailsButton, default_toggle_details_button   
-from domible import open_html_in_browser, open_object_in_browser 
+from domible import open_html_document_in_browser, open_object_in_browser 
 from domible.starterDocuments import basic_head_empty_body
 from domible.elements import Html, Body, BaseElement, Heading
 
@@ -84,7 +84,7 @@
         for name, obj in cases.items():
             elem = element_from_object(obj, depth)
             body.add_content([Heading(2, f"Object {name}"), elem])
-        open_html_in_browser(html)
+        open_html_document_in_browser(html)
         # print the HTML in case I want to redirect output to a file.
         # it's easier than supporting writing to a file in this code.
         if len(argv) > 3 and argv[3] == "print":