django-datashow 0.1.0__tar.gz

django_datashow-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+.python-version
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+*.mo

django_datashow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2025, Open Knowledge Foundation Deutschland e.V. / Stefan Wehrmeyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

django_datashow-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: django-datashow
+Version: 0.1.0
+Summary: Present your datasets on your django site
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: django-admin-sortable2>=2
+Requires-Dist: django>=4.2
+Requires-Dist: markdown>=3.7
+Description-Content-Type: text/markdown
+
+# django-datashow
+
+A Django app to show SQLite datasets as tables with configurable features:
+
+- column value formatting
+- column sorting
+- column facets and filters
+- searching via SQLite's FTS5
+- pagination
+- exporting to CSV
+- row-level detail view.
+
+This app is designed for read-only (or rarely updated) datasets that you want to publish on the web and where you control and trust the content.
+
+## Installation
+
+```
+pip install django-datashow
+```
+
+Add `datashow` to your `INSTALLED_APPS` in `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    'datashow',
+    ...
+]
+```
+
+Hook up the `datashow` URLs in your project's `urls.py`:
+
+```python
+from django.urls import path, include
+
+urlpatterns = [
+    ...
+    path('data/', include('datashow.urls')),
+    ...
+]
+```
+
+
+## Settings
+
+You can configure the following settings in your `settings.py`:
+
+- `DATASHOW_DB_CACHE_PATH`: Path to the SQLite database cache directory. If not set, uses a temporary directory. When the SQLite file needs to be read, it gets copied from your MEDIA storage to this cache path. A new dataset version invalidates the cache.
+- `DATASHOW_STORAGE_BACKEND`: The Django storage backend name to use for storing the SQLite files. Default is `"default"`.

django_datashow-0.1.0/README.md

@@ -0,0 +1,49 @@
+# django-datashow
+
+A Django app to show SQLite datasets as tables with configurable features:
+
+- column value formatting
+- column sorting
+- column facets and filters
+- searching via SQLite's FTS5
+- pagination
+- exporting to CSV
+- row-level detail view.
+
+This app is designed for read-only (or rarely updated) datasets that you want to publish on the web and where you control and trust the content.
+
+## Installation
+
+```
+pip install django-datashow
+```
+
+Add `datashow` to your `INSTALLED_APPS` in `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    'datashow',
+    ...
+]
+```
+
+Hook up the `datashow` URLs in your project's `urls.py`:
+
+```python
+from django.urls import path, include
+
+urlpatterns = [
+    ...
+    path('data/', include('datashow.urls')),
+    ...
+]
+```
+
+
+## Settings
+
+You can configure the following settings in your `settings.py`:
+
+- `DATASHOW_DB_CACHE_PATH`: Path to the SQLite database cache directory. If not set, uses a temporary directory. When the SQLite file needs to be read, it gets copied from your MEDIA storage to this cache path. A new dataset version invalidates the cache.
+- `DATASHOW_STORAGE_BACKEND`: The Django storage backend name to use for storing the SQLite files. Default is `"default"`.

django_datashow-0.1.0/datashow/admin.py

@@ -0,0 +1,159 @@
+from adminsortable2.admin import SortableAdminMixin
+from django.contrib import admin
+from django.forms import ModelForm
+from django.http import HttpRequest
+from django.utils.translation import gettext_lazy as _
+
+from .models import Column, Dataset, Table
+from .table import initialize_dataset, setup_fts
+
+
+@admin.register(Dataset)
+class DatasetAdmin(admin.ModelAdmin):
+    list_display = ("name", "created_at", "updated_at", "version", "public", "listed")
+    list_filter = ("public", "listed")
+    search_fields = ("name", "slug")
+    readonly_fields = (
+        "created_at",
+        "updated_at",
+    )
+    prepopulated_fields = {"slug": ("name",)}
+    raw_id_fields = ("default_table",)
+    actions = ["initialize_dataset"]
+
+    def save_model(
+        self, request: HttpRequest, obj: Dataset, form: ModelForm, change: bool
+    ) -> None:
+        super().save_model(request, obj, form, change)
+        if not obj.tables.exists():
+            initialize_dataset(obj)
+
+    @admin.action(description=_("Initialize datasets"))
+    def initialize_dataset(self, request: HttpRequest, queryset):
+        for dataset in queryset:
+            initialize_dataset(dataset)
+        self.message_user(request, _("Datasets initialized."))
+
+
+class ColumnInline(admin.StackedInline):
+    model = Column
+    extra = 0
+    fields = (
+        "label",
+        "visible",
+        "visible_detail",
+        "sortable",
+        "searchable",
+        "facet_count",
+        "prefix",
+        "postfix",
+        "formatter",
+        "formatter_arguments",
+        "filter",
+        "filter_arguments",
+    )
+    ordering = ("order",)
+    show_change_link = True
+
+
+@admin.register(Table)
+class TableAdmin(admin.ModelAdmin):
+    inlines = [ColumnInline]
+    list_display = ("name", "dataset", "row_count", "visible")
+    search_fields = ("name", "slug")
+    raw_id_fields = ("primary_key",)
+    save_on_top = True
+    list_filter = ("dataset", "visible")
+    actions = ["generate_fts"]
+    fieldsets = (
+        (
+            None,
+            {
+                "fields": (
+                    "slug",
+                    "label",
+                    "description",
+                    "visible",
+                    "row_label_template",
+                    "primary_key",
+                    "pagination_size",
+                )
+            },
+        ),
+        (
+            _("Advanced"),
+            {
+                "classes": ["collapse"],
+                "fields": [
+                    "name",
+                    "sql",
+                    "dataset",
+                    "row_count",
+                ],
+            },
+        ),
+    )
+
+    @admin.action(description=_("Generate FTS tables"))
+    def generate_fts(self, request: HttpRequest, queryset):
+        for table in queryset:
+            setup_fts(table)
+
+
+@admin.register(Column)
+class ColumnAdmin(SortableAdminMixin, admin.ModelAdmin):
+    search_fields = ("name", "label")
+    list_filter = ("table", "visible", "visible_detail", "sortable", "searchable")
+    list_display = (
+        "name",
+        "label",
+        "table",
+        "visible",
+        "visible_detail",
+        "sortable",
+        "searchable",
+        "facet_count",
+    )
+
+    actions = [
+        "make_visible",
+        "make_invisible",
+        "make_visible_detail",
+        "make_invisible_detail",
+        "make_sortable",
+        "make_unsortable",
+        "make_searchable",
+        "make_unsearchable",
+    ]
+
+    @admin.action(description=_("Make visible"))
+    def make_visible(self, request: HttpRequest, queryset):
+        queryset.update(visible=True)
+
+    @admin.action(description=_("Make invisible"))
+    def make_invisible(self, request: HttpRequest, queryset):
+        queryset.update(visible=False)
+
+    @admin.action(description=_("Make visible_detail"))
+    def make_visible_detail(self, request: HttpRequest, queryset):
+        queryset.update(visible_detail=True)
+
+    @admin.action(description=_("Make invisible_detail"))
+    def make_invisible_detail(self, request: HttpRequest, queryset):
+        queryset.update(visible_detail=False)
+
+    @admin.action(description=_("Make sortable"))
+    def make_sortable(self, request: HttpRequest, queryset):
+        queryset.update(sortable=True)
+
+    @admin.action(description=_("Make unsortable"))
+    def make_unsortable(self, request: HttpRequest, queryset):
+        queryset.update(sortable=False)
+
+    @admin.action(description=_("Make searchable"))
+    def make_searchable(self, request: HttpRequest, queryset):
+        queryset.update(searchable=True)
+
+    @admin.action(description=_("Make unsearchable"))
+    def make_unsearchable(self, request: HttpRequest, queryset):
+        queryset.update(searchable=False)

django_datashow-0.1.0/datashow/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class DatashowConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "datashow"

django_datashow-0.1.0/datashow/db.py

@@ -0,0 +1,85 @@
+import sqlite3
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+
+from django.core.files.base import ContentFile
+
+from .models import Dataset
+from .settings import DATASHOW_DB_CACHE_PATH
+
+
+def get_database_filename(dataset: Dataset) -> str:
+    return "datashow-dataset-{}-{}.sqlite".format(dataset.id, dataset.version)
+
+
+def get_database_file(dataset: Dataset) -> Path:
+    filename = get_database_filename(dataset)
+    if DATASHOW_DB_CACHE_PATH is None:
+        base_path = Path(tempfile.gettempdir())
+    else:
+        base_path = Path(DATASHOW_DB_CACHE_PATH)
+
+    filepath = base_path / filename
+    if filepath.exists():
+        return filepath
+
+    base_path.mkdir(exist_ok=True)
+
+    with dataset.sqlite_file.open("rb") as sqlite_file:
+        with open(filepath, "wb") as cache_file:
+            cache_file.write(sqlite_file.read())
+
+    return filepath
+
+
+def get_database_connection(dataset: Dataset):
+    filepath = get_database_file(dataset)
+    return sqlite3.connect("file:{}?mode=ro".format(filepath), uri=True)
+
+
+@contextmanager
+def open_db(dataset):
+    connection = get_database_connection(dataset)
+    try:
+        yield connection
+    finally:
+        connection.close()
+
+
+@contextmanager
+def open_cursor(dataset):
+    with open_db(dataset) as connection:
+        cursor = connection.cursor()
+        try:
+            yield cursor
+        finally:
+            cursor.close()
+
+
+@contextmanager
+def open_write_cursor(dataset: Dataset):
+    filepath = get_database_file(dataset)
+    connection = sqlite3.connect(
+        "file:{}".format(filepath), uri=True, isolation_level="EXCLUSIVE"
+    )
+    assert not connection.in_transaction
+    try:
+        cursor = connection.cursor()
+
+        cursor.execute("PRAGMA JOURNAL_MODE = DELETE;")
+        # Smaller page size for better performance when using HTTP range requests
+        cursor.execute("PRAGMA page_size = 1024;")
+        yield cursor
+    finally:
+        cursor.execute("COMMIT;")
+        cursor.execute("VACUUM;")
+        connection.commit()
+        connection.close()
+
+    # Write database back to origin and update version
+    with open(filepath, "rb") as cache_file:
+        new_sqlite = ContentFile(cache_file.read())
+    dataset.version += 1
+    filename = get_database_filename(dataset)
+    dataset.sqlite_file.save(filename, new_sqlite, save=True)

django_datashow-0.1.0/datashow/fields.py

@@ -0,0 +1,83 @@
+from django import forms
+
+# from django.template.loader import render_to_string
+from django.utils.translation import gettext_lazy as _
+
+
+class RangeWidget(forms.MultiWidget):
+    template_name = "datashow/widgets/range.html"
+
+    def __init__(self, widget, *args, **kwargs):
+        self.prefix = kwargs.pop("prefix", "")
+        self.postfix = kwargs.pop("postfix", "")
+        super().__init__(widgets=(widget, widget), *args, **kwargs)
+        self.widgets_names = ["_min", "_max"]
+
+    def decompress(self, value):
+        return value
+
+    def get_context(self, name, value, attrs):
+        ctx = super().get_context(name, value, attrs)
+        ctx["prefix"] = self.prefix
+        ctx["postfix"] = self.postfix
+        return ctx
+
+
+class RangeField(forms.MultiValueField):
+    default_error_messages = {
+        "invalid_start": _("Enter a valid start value."),
+        "invalid_end": _("Enter a valid end value."),
+    }
+
+    def __init__(
+        self,
+        field_class,
+        min_value=None,
+        max_value=None,
+        prefix="",
+        postfix="",
+        widget=forms.TextInput,
+        *args,
+        **kwargs,
+    ):
+        if "initial" not in kwargs:
+            kwargs["initial"] = ["", ""]
+
+        fields = (
+            field_class(
+                min_value=min_value,
+                max_value=max_value,
+            ),
+            field_class(
+                min_value=min_value,
+                max_value=max_value,
+            ),
+        )
+
+        super().__init__(
+            fields=fields,
+            widget=RangeWidget(widget, prefix=prefix, postfix=postfix),
+            *args,
+            **kwargs,
+        )
+
+    def compress(self, data_list):
+        if data_list:
+            return [
+                self.fields[0].clean(data_list[0]),
+                self.fields[1].clean(data_list[1]),
+            ]
+        return None
+
+
+class CommaSeparatedMultiChoiceField(forms.MultipleChoiceField):
+    default_error_messages = {
+        "invalid_start": _("Enter a valid start value."),
+        "invalid_end": _("Enter a valid end value."),
+    }
+
+    def to_python(self, value):
+        if value is None:
+            return []
+        value = value.split(",")
+        return [str(val) for val in value]

django_datashow-0.1.0/datashow/formatters.py

@@ -0,0 +1,113 @@
+import re
+from datetime import datetime
+
+from django.contrib.humanize.templatetags.humanize import intcomma
+from django.utils import formats
+from django.utils.html import format_html
+from django.utils.safestring import mark_safe
+from django.utils.translation import gettext_lazy as _
+
+from .models import FormaterChoices
+
+TRAILING_ZERO = re.compile(r"[,\.]0+$")
+
+
+def render_value(column, value):
+    return format_html(
+        "{prefix}{value}{postfix}",
+        prefix=column.prefix,
+        value=value,
+        postfix=column.postfix,
+    )
+
+
+def try_format(args, key, row_data, default=""):
+    try:
+        value = args[key]
+        return value.format(**row_data)
+    except (KeyError, ValueError):
+        return default
+
+
+ALIGN_RIGHT = "text-end"
+ALIGN_CENTER = "text-center"
+
+
+def format_column(column):
+    css = ""
+    formatter = column.formatter
+    if formatter == FormaterChoices.FLOAT:
+        css = ALIGN_RIGHT
+    elif formatter == FormaterChoices.INTEGER:
+        css = ALIGN_RIGHT
+    elif formatter == FormaterChoices.DATE:
+        css = ALIGN_RIGHT
+    elif formatter == FormaterChoices.DATETIME:
+        css = ALIGN_RIGHT
+    elif formatter == FormaterChoices.BOOLEAN:
+        css = ALIGN_CENTER
+    return css
+
+
+def format_value(column, value, row_data, detail=False):
+    css = ""
+    formatter = column.formatter
+    if value is None:
+        if formatter == FormaterChoices.BOOLEAN:
+            css = ALIGN_CENTER
+        if formatter in (
+            FormaterChoices.FLOAT,
+            FormaterChoices.INTEGER,
+            FormaterChoices.DATE,
+            FormaterChoices.DATETIME,
+        ):
+            css = ALIGN_RIGHT
+        return css, mark_safe('<span class="text-secondary">–</span>')
+
+    args = column.formatter_arguments
+    if formatter == FormaterChoices.FLOAT:
+        value = intcomma(value)
+        css = ALIGN_RIGHT
+    elif formatter == FormaterChoices.INTEGER:
+        value = TRAILING_ZERO.sub("", intcomma(value))
+        css = ALIGN_RIGHT
+    elif formatter == FormaterChoices.DATE:
+        value = formats.date_format(datetime.fromisoformat(value), "SHORT_DATE_FORMAT")
+        css = ALIGN_RIGHT
+    elif formatter == FormaterChoices.DATETIME:
+        value = formats.date_format(
+            datetime.fromisoformat(value), "SHORT_DATETIME_FORMAT"
+        )
+        css = ALIGN_RIGHT
+    elif formatter == FormaterChoices.BOOLEAN:
+        if value:
+            value = mark_safe('<span class="text-success">✅</span>')
+        else:
+            value = mark_safe('<span class="text-danger">❌</span>')
+        css = ALIGN_CENTER
+    elif formatter == FormaterChoices.LINK:
+        url = try_format(args, "url", row_data, "")
+        value = format_html(
+            '<a href="{href}">{link}</a>',
+            href=url,
+            link=value,
+        )
+    elif formatter == FormaterChoices.SUMMARY:
+        if not detail:
+            summary = try_format(args, "summary", row_data, _("Details"))
+            value = format_html(
+                '<details class="datashow-summary"><summary><span>{summary}</span></summary>{details}</details>',
+                summary=summary,
+                details=value,
+            )
+    elif formatter == FormaterChoices.ABBREVIATION:
+        title = try_format(args, "title", row_data, None)
+        if title is None:
+            value = format_html("<abbr>{value}</abbr>", value=value)
+        else:
+            value = format_html(
+                '<abbr title="{title}">{value}</abbr>',
+                title=title,
+                value=value,
+            )
+    return css, render_value(column, value)

django_datashow-0.1.0/datashow/forms.py

@@ -0,0 +1,82 @@
+from typing import NamedTuple
+
+from django import forms
+from django.utils.translation import gettext_lazy as _
+
+from .fields import CommaSeparatedMultiChoiceField, RangeField
+from .models import FilterChoices
+
+SEARCH_PARAM = "q"
+SORT_PARAM = "sort"
+
+
+class SqlParts(NamedTuple):
+    from_sql: list[str]
+    where_sql: list[str]
+    where_params: list
+
+
+class FilterForm(forms.Form):
+    def __init__(self, table, *args, **kwargs):
+        self.table = table
+        super().__init__(*args, **kwargs)
+        sortable_columns = [col.name for col in self.table.get_sortable_columns()]
+        if sortable_columns:
+            self.fields[SORT_PARAM] = CommaSeparatedMultiChoiceField(
+                label=_("Sort by"),
+                choices=[("", "0")]
+                + [(col, col) for col in sortable_columns]
+                + [("-" + col, "-" + col) for col in sortable_columns],
+                required=False,
+                widget=forms.HiddenInput,
+            )
+        self.set_facet_fields()
+        self.set_filter_fields()
+
+    def set_facet_fields(self):
+        facet_columns = self.table.get_facet_columns()
+        for column in facet_columns:
+            self.fields[column.name] = forms.CharField(
+                label=column.label,
+                required=False,
+                widget=forms.HiddenInput(),
+            )
+
+    def set_filter_fields(self):
+        if self.table.has_fts():
+            self.fields[SEARCH_PARAM] = forms.CharField(
+                label=_("Search term"),
+                required=False,
+                widget=forms.TextInput(attrs={"class": "form-control"}),
+            )
+        filter_columns = self.table.get_filter_columns()
+        for column in filter_columns:
+            column_filter = column.filter
+            if column_filter == FilterChoices.INTEGER_RANGE:
+                field_name = column.name + "__range"
+                self.fields[field_name] = RangeField(
+                    forms.IntegerField,
+                    label=column.label,
+                    min_value=column.filter_arguments.get("min"),
+                    max_value=column.filter_arguments.get("max"),
+                    prefix=column.prefix,
+                    postfix=column.postfix,
+                    required=False,
+                    widget=forms.TextInput(
+                        attrs={
+                            "class": "form-control text-end",
+                            "inputmode": "numeric",
+                            "type": "number",
+                            "min": column.filter_arguments.get("min", ""),
+                            "max": column.filter_arguments.get("max", ""),
+                        }
+                    ),
+                )
+
+    def has_filter(self):
+        return any(k for k in self.fields.keys() if k != SORT_PARAM)
+
+    def is_filtered(self):
+        if not self.is_valid():
+            return False
+        return any(v for k, v in self.cleaned_data.items() if k != SORT_PARAM)