Optional HTML representations for Jupyter Notebook

CHANGELOG.md

@@ -9,6 +9,7 @@
 - Replace test.com with special-use domain name. ([#769](https://github.com/stac-utils/pystac/pull/769))
 - Updated AssetDefinition to have create, apply methods ([#768](https://github.com/stac-utils/pystac/pull/768))
 - Add Grid Extension support ([#799](https://github.com/stac-utils/pystac/pull/799))
+- Rich HTML representations for Jupyter Notebook display ([#743](https://github.com/stac-utils/pystac/pull/743))
 
 ### Removed
 

mypy.ini

@@ -2,6 +2,9 @@
 show_error_codes = True
 strict = True
 
+[mypy-jinja2.*]
+ignore_missing_imports = True
+
 [mypy-jsonschema.*]
 ignore_missing_imports = True
 

pystac/asset.py

@@ -1,7 +1,9 @@
+from html import escape
 from copy import copy
 from typing import Any, Dict, List, Optional, TYPE_CHECKING, Union
 
 from pystac import common_metadata
+from pystac.html.jinja_env import get_jinja_env
 from pystac import utils
 
 if TYPE_CHECKING:
@@ -156,6 +158,14 @@ def common_metadata(self) -> "CommonMetadata_Type":
     def __repr__(self) -> str:
         return "<Asset href={}>".format(self.href)
 
+    def _repr_html_(self) -> str:
+        jinja_env = get_jinja_env()
+        if jinja_env:
+            template = jinja_env.get_template("Asset.jinja2")
+            return str(template.render(asset=self))
+        else:
+            return escape(repr(self))
+
     @classmethod
     def from_dict(cls, d: Dict[str, Any]) -> "Asset":
         """Constructs an Asset from a dict.

pystac/catalog.py

@@ -1,6 +1,8 @@
 import os
+from html import escape
 from copy import deepcopy
 from pystac.errors import STACTypeError
+from pystac.html.jinja_env import get_jinja_env
 from typing import (
     Any,
     Callable,
@@ -196,6 +198,14 @@ def __init__(
     def __repr__(self) -> str:
         return "<Catalog id={}>".format(self.id)
 
+    def _repr_html_(self) -> str:
+        jinja_env = get_jinja_env()
+        if jinja_env:
+            template = jinja_env.get_template("Catalog.jinja2")
+            return str(template.render(catalog=self))
+        else:
+            return escape(repr(self))
+
     def set_root(self, root: Optional["Catalog"]) -> None:
         STACObject.set_root(self, root)
         if root is not None:

pystac/collection.py

@@ -1,6 +1,8 @@
+from html import escape
 from copy import deepcopy
 from datetime import datetime
 from pystac.errors import STACTypeError
+from pystac.html.jinja_env import get_jinja_env
 from typing import (
     Any,
     Dict,
@@ -525,6 +527,14 @@ def __init__(
     def __repr__(self) -> str:
         return "<Collection id={}>".format(self.id)
 
+    def _repr_html_(self) -> str:
+        jinja_env = get_jinja_env()
+        if jinja_env:
+            template = jinja_env.get_template("Collection.jinja2")
+            return str(template.render(catalog=self))
+        else:
+            return escape(repr(self))
+
     def add_item(
         self,
         item: "Item_Type",

pystac/html/Asset.jinja2

@@ -0,0 +1,31 @@
+{% import 'Macros.jinja2' as macros %}
+
+<div class="jp-RenderedHTMLCommon jp-RenderedHTML jp-mod-trusted jp-OutputArea-output">
+    {{ macros.square('#FED7E5', '#FA4C8C') }}
+    <div>
+        <details style="margin-left: 48px;">
+            <summary style="margin-bottom: 20px;">
+                <h3 style="margin-bottom: 0px; display: inline;">Asset: {{ asset.title }}</h3>
+            </summary>
+            <table style="width: 100%; text-align: left;">
+                <tr><td style="text-align: left;"><strong>href</strong>: {{ asset.href }} </td></tr>
+                {% if asset.title %}
+                    <tr><td style="text-align: left;"><strong>Title:</strong> {{ asset.title }} </td></tr>
+                {% endif %}
+                {% if asset.description %}
+                    <tr><td style="text-align: left;"><strong>Description:</strong> {{ asset.description }} </td></tr>
+                {% endif %}
+                {% if asset.media_type %}
+                    <tr><td style="text-align: left;"><strong>Media type:</strong> {{ asset.media_type }} </td></tr>
+                {% endif %}
+                {% if asset.roles %}
+                    <tr><td style="text-align: left;"><strong>Roles:</strong> {{ asset.roles }} </td></tr>
+                {% endif %}
+                {% if asset.owner %}
+                    <tr><td style="text-align: left;"><strong>Owner:</strong> {{ asset.Owner }} </td></tr>
+                {% endif %}
+                {{ macros.extra_fields(asset) }}
+            </table>
+        </details>
+    </div>
+</div>

pystac/html/Catalog.jinja2

@@ -0,0 +1,30 @@
+{% import 'Macros.jinja2' as macros %}
+
+<div class="jp-RenderedHTMLCommon jp-RenderedHTML jp-mod-trusted jp-OutputArea-output">
+    {{ macros.square() }}
+    <div>
+        <details style="margin-left: 48px;">
+            <summary style="margin-bottom: 20px;">
+                <h3 style="margin-bottom: 0px; display: inline;">
+                    {{catalog.__class__.__name__}}: {{catalog.id}}
+                </h3>
+            </summary>
+            <table style="width: 100%; text-align: left;">
+                <tr><td style="text-align: left;">ID: {{catalog.id}} </td></tr>
+                {% if catalog.title %}
+                    <tr><td style="text-align: left;"><strong>Title:</strong> {{catalog.title}} </td></tr>
+                {% endif %}
+                {% if catalog.description %}
+                    <tr><td style="text-align: left;"><strong>Description:</strong> {{catalog.description}} </td></tr>
+                {% endif %}
+                {% block subclass_fields %} {% endblock %}
+                {{ macros.extra_fields(catalog) }}
+            </table>
+            {{ macros.stac_extensions(catalog) }}
+            {{ macros.children(catalog) }}
+            {{ macros.items(catalog) }}
+            {{ macros.links(catalog) }}
+            {% block subclass_details %} {% endblock %}
+        </details>
+    </div>
+</div>

pystac/html/Collection.jinja2

@@ -0,0 +1,20 @@
+{% extends 'Catalog.jinja2' %}
+{% import 'Macros.jinja2' as macros %}
+
+{% block subclass_fields %}
+    {# Providers field #}
+    {% if catalog.providers %}
+        <tr><td style="text-align: left;"><strong>Providers:</strong>
+        <ul>
+        {% for provider in catalog.providers %}
+             <li>{{ provider._repr_html_() }}</li>
+        {% endfor %}
+        </ul>
+        </td></tr>
+    {% endif %}
+{% endblock %}
+
+{% block subclass_details %}
+    {{ macros.assets(catalog) }}
+{% endblock %}
+

pystac/html/Item.jinja2

@@ -0,0 +1,33 @@
+{% import 'Macros.jinja2' as macros %}
+
+<div class="jp-RenderedHTMLCommon jp-RenderedHTML jp-mod-trusted jp-OutputArea-output">
+    {{ macros.square('#DBF5FF', '#4CC9FF') }}
+    <div>
+        <details style="margin-left: 48px;">
+            <summary style="margin-bottom: 20px;">
+                <h3 style="margin-bottom: 0px; display: inline;">Item: {{item.id}}</h3>
+            </summary>
+            <table style="width: 100%; text-align: left;">
+                <tr><td style="text-align: left;"><strong>ID</strong>: {{item.id}} </td></tr>
+                {% if item.title %}
+                    <tr><td style="text-align: left;"><strong>Title:</strong> {{item.title}} </td></tr>
+                {% endif %}
+                {% if item.bbox %}
+                    <tr><td style="text-align: left;"><strong>Bounding Box:</strong> {{item.bbox}} </td></tr>
+                {% endif %}
+                {% if item.datetime %}
+                    <tr><td style="text-align: left;"><strong>Datetime:</strong> {{item.datetime}} </td></tr>
+                {% endif %}
+                {% if item.properties %}
+                    {% for key in item.properties %}
+                        <tr><td style="text-align: left;"><strong>{{ key }}:</strong> {{ item.properties[key] }} </td></tr>
+                    {% endfor %}
+                {% endif %}
+                {{ macros.extra_fields(item) }}
+            </table>
+            {{ macros.stac_extensions(item) }}
+            {{ macros.assets(item) }}
+            {{ macros.links(item) }}
+        </details>
+    </div>
+</div>

pystac/html/ItemCollection.jinja2

@@ -0,0 +1,31 @@
+{% import 'Macros.jinja2' as macros %}
+
+<div class="jp-RenderedHTMLCommon jp-RenderedHTML jp-mod-trusted jp-OutputArea-output">
+    {{ macros.square() }}
+    <div>
+        <details style="margin-left: 48px;">
+            <summary style="margin-bottom: 20px;">
+                <h3 style="margin-bottom: 0px; display: inline;">
+                    {{item_collection.__class__.__name__}}
+                </h3>
+            </summary>
+            <table style="width: 100%; text-align: left;">
+                {{ macros.extra_fields(item_collection) }}
+            </table>
+
+            {% if item_collection.__iter__()|is_nonempty_generator %}
+                <details>
+                    {% if item_collection.items | length > 10 %}
+                        <i> Only the first 10 items shown </i>
+                    {% endif %}
+                    <summary style="margin-bottom: 10px; margin-top: 10px">
+                        <h4 style="margin-bottom: 0px; display: inline;">Items</h4>
+                    </summary>
+                    {% for item in item_collection.items[:10] %}
+                        {{ item._repr_html_() }}
+                    {% endfor %}
+                </details>
+            {% endif %}
+        </details>
+    </div>
+</div>

pystac/html/Link.jinja2

@@ -0,0 +1,23 @@
+{% import 'Macros.jinja2' as macros %}
+
+<div class="jp-RenderedHTMLCommon jp-RenderedHTML jp-mod-trusted jp-OutputArea-output">
+    {{ macros.square('#FFF7E5', '#FF6132') }}
+    <div style="margin-left: 48px;">
+        <h4 style="margin-bottom: 0px;">Link: {{ link.id }}</h4>
+        {% if link.title %}
+            <p style="color: #9D9D9D; margin-bottom: 0px;">{{ link.title }}</p>
+        {% endif %}
+        <table style="width: 100%; text-align: left;">
+            <tr><td style="text-align: left;"><strong>Rel:</strong> {{ link.rel }} </td></tr>
+            <tr><td style="text-align: left;"><strong>Target:</strong> {{ link.target }} </td></tr>
+            {% if link.media_type %}
+                <tr><td style="text-align: left;"><strong>Media Type:</strong> {{ link.media_type }} </td></tr>
+            {% endif %}
+            {{ macros.extra_fields(link) }}
+        </table>
+        {% if link.extra_fields %}
+            <table style="width: 100%; text-align: left;">
+            </table>
+        {% endif %}
+    </div>
+</div>

pystac/html/Macros.jinja2

@@ -0,0 +1,93 @@
+{% macro square(background_color='#E1E1E1', border_color='#9D9D9D') -%}
+    <div style="
+        width: 24px;
+        height: 24px;
+        background-color: {{ background_color }};
+        border: 3px solid {{ border_color }};
+        border-radius: 5px;
+        position: absolute;">
+    </div>
+{%- endmacro %}
+
+
+{% macro extra_fields(parent) -%}
+    {% if parent.extra_fields %}
+        {% for key, value in parent.extra_fields.items() %}
+            <tr><td style="text-align: left;"><strong>{{ key }}:</strong> {{ value }} </td></tr>
+        {% endfor %}
+    {% endif %}
+{%- endmacro %}
+
+
+{% macro links(parent) -%}
+    {% if parent.links|length > 0 %}
+        <details>
+            <summary style="margin-bottom: 10px; margin-top: 10px">
+                <h4 style="margin-bottom: 0px; display: inline;">Links</h4>
+            </summary>
+            {% for link in parent.links %}
+                {{ link._repr_html_() }}
+            {% endfor %}
+        </details>
+    {% endif %}
+{%- endmacro %}
+
+
+{% macro items(parent) -%}
+    {% if parent.get_items()|is_nonempty_generator %}
+        <details>
+            <summary style="margin-bottom: 10px; margin-top: 10px">
+                <h4 style="margin-bottom: 0px; display: inline;">Items</h4>
+            </summary>
+            <i> Only the first item shown </i>
+            {% for item in parent.get_items()|first %}
+                {{ item._repr_html_() }}
+            {% endfor %}
+        </details>
+    {% endif %}
+{%- endmacro %}
+
+
+{% macro children(parent) -%}
+    {% if parent.get_children()|is_nonempty_generator %}
+        <details>
+            <summary style="margin-bottom: 10px; margin-top: 10px">
+                <h4 style="margin-bottom: 0px; display: inline;">Children</h4>
+            </summary>
+            <i> Only the first child shown </i>
+            {% for child in parent.get_children()|first %}
+                {{ child._repr_html_() }}
+            {% endfor %}
+        </details>
+    {% endif %}
+{%- endmacro %}
+
+
+{% macro stac_extensions(parent) -%}
+    {% if parent.stac_extensions|length > 0 %}
+        <details>
+            <summary style="margin-bottom: 10px; margin-top: 10px;">
+                <h4 style="margin-bottom: 0px; display: inline;">STAC Extensions</h4>
+            </summary>
+            <table style="width: 100%; text-align: left;">
+                {% for stac_extension in parent.stac_extensions %}
+                    <tr><td style="text-align: left;"><a href="{{stac_extension}}">{{stac_extension}}</a></td></tr>
+                {% endfor %}
+            </table>
+        </details>
+    {% endif %}
+{%- endmacro %}
+
+
+{% macro assets(parent) -%}
+    {% if parent.assets|length > 0 %}
+        <details>
+            <summary style="margin-bottom: 10px; margin-top: 10px;">
+                <h4 style="margin-bottom: 0px; display: inline;">Assets</h4>
+            </summary>
+            {% for key, asset in parent.assets.items() %}
+                {{ asset._repr_html_() }}
+            {% endfor %}
+        </details>
+    {% endif %}
+{%- endmacro %}

pystac/html/Provider.jinja2

@@ -0,0 +1,12 @@
+{% import 'Macros.jinja2' as macros %}
+
+<div>
+    {% if provider.url %}
+        <a href="{{ provider.url }}"> {{ provider.name }} </a>
+    {% else %}
+        {{ provider.name }}
+    {% endif %}
+    (<i>{{ provider.roles|join(", ") }}</i>){% if provider.description %}: {{ provider.description }} {% endif %}
+    {{ macros.extra_fields(provider) }}
+</div>
+

pystac/html/__init__.py

@@ -0,0 +1,3 @@
+from .jinja_env import get_jinja_env
+
+__all__ = ["get_jinja_env"]

pystac/html/jinja_env.py

@@ -0,0 +1,19 @@
+from functools import lru_cache
+from itertools import islice
+
+
+@lru_cache()
+def get_jinja_env():  # type: ignore
+    try:
+        from jinja2 import Environment, PackageLoader, select_autoescape
+    except ModuleNotFoundError:
+        return None
+
+    environment = Environment(
+        loader=PackageLoader("pystac", "html"), autoescape=select_autoescape()
+    )
+
+    environment.filters["first"] = lambda x: islice(x, 1)
+    environment.filters["is_nonempty_generator"] = lambda x: next(x, None) is not None
+
+    return environment