Implement urwid image widget

CHANGELOG.md

@@ -21,6 +21,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `write_tty()`
 - Support for clearing *kitty* images by z-index ([97eceab]).
 - Support for clearing *iterm2* images on konsole by intersection with cursor position ([807a9ec]).
+- Widgets and related classes to display images with [urwid](https://urwid.org) ([#73]).
+  - `term_image.widget` subpackage
+  - `term_image.widget.UrwidImage`
+  - `term_image.widget.UrwidImageCanvas`
+  - `term_image.widget.UrwidImageJanitor`
+  - `term_image.widget.UrwidImageScreen`
 
 ### Changed
 - **(BREAKING!)** Redefined `KittyImage.clear()` ([97eceab]).
@@ -36,6 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 [#70]: https://github.com/AnonymouX47/term-image/pull/70
 [#72]: https://github.com/AnonymouX47/term-image/pull/72
+[#73]: https://github.com/AnonymouX47/term-image/pull/73
 [#74]: https://github.com/AnonymouX47/term-image/pull/74
 [b4533d5]: https://github.com/AnonymouX47/term-image/commit/b4533d5697d41fe0742c2ac895077da3b8d889dc
 [97eceab]: https://github.com/AnonymouX47/term-image/commit/97eceab77e7448a18281aa6edb3fa8ec9e6564c5

Makefile

@@ -62,9 +62,10 @@ uninstall:
 # Tests
 
 test-all: test test-url
-test: test-base test-iterator test-others test-graphics test-text
+test: test-base test-iterator test-others test-graphics test-text test-widget
 test-graphics: test-kitty test-iterm2
 test-text: test-block
+test-widget: test-urwid
 
 # Executing using `python -m` adds CWD to `sys.path`.
 
@@ -88,3 +89,6 @@ test-block:
 
 test-url:
 	python -m pytest -v tests/test_url.py
+
+test-urwid:
+	python -m pytest -v tests/test_widget/test_urwid.py

docs/requirements.txt

@@ -1,2 +1,3 @@
 sphinx==6.1.2
 furo==2022.12.7
+urwid==2.1.2

docs/source/index.rst

@@ -100,7 +100,6 @@ In no particular order:
 * Use ``termpile`` for URL-sourced images
 * Source images from raw pixel data
 * IPython Extension
-* Addition of urwid widgets for displaying images
 * etc...
 
 

docs/source/reference/index.rst

@@ -16,6 +16,7 @@ Reference
    :caption: Sub-sections:
 
    image
+   widget
    exceptions
    utils
 

docs/source/reference/widget.rst

@@ -0,0 +1,8 @@
+TUI Widgets
+===========
+
+.. automodule:: term_image.widget
+   :members:
+   :show-inheritance:
+
+   The ``term_image.widget`` module defines the following:

src/term_image/exceptions.py

@@ -70,6 +70,13 @@ class KittyImageError(GraphicsImageError):
     """
 
 
+# Widgets
+
+
+class UrwidImageError(TermImageError):
+    """Raised for errors specific to :py:class:`~term_image.widget.UrwidImage`."""
+
+
 __all__ = ["TermImageWarning"] + [
     name
     for name, obj in vars().items()

src/term_image/widget/__init__.py

@@ -0,0 +1,20 @@
+""".. Image widgets for TUI frameworks"""
+
+from __future__ import annotations
+
+__all__ = []
+
+try:
+    import urwid
+except ImportError:
+    pass
+else:
+    from .urwid import UrwidImage, UrwidImageCanvas, UrwidImageJanitor, UrwidImageScreen
+
+    del urwid
+    __all__ += [
+        "UrwidImage",
+        "UrwidImageCanvas",
+        "UrwidImageJanitor",
+        "UrwidImageScreen",
+    ]