invenio-banners 5.2.1__py2.py3-none-any.whl

invenio_banners/__init__.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2020-2024 CERN.
+# Copyright (C) 2024-2025 Graz University of Technology.
+# Copyright (C) 2025      KTH Royal Institute of Technology.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Create and show banners with useful messages to users."""
+
+from .ext import InvenioBanners
+
+__version__ = "5.2.1"
+
+__all__ = ("__version__", "InvenioBanners")

invenio_banners/administration/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2023 CERN.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Administration banners module."""

invenio_banners/administration/banners.py

@@ -0,0 +1,183 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2023 CERN.
+# Copyright (C) 2024 KTH Royal Institute of Technology.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Invenio administration banners view module."""
+
+from invenio_administration.views.base import (
+    AdminResourceCreateView,
+    AdminResourceDetailView,
+    AdminResourceEditView,
+    AdminResourceListView,
+)
+from invenio_i18n import lazy_gettext as _
+
+
+class BannerListView(AdminResourceListView):
+    """Search admin view."""
+
+    api_endpoint = "/banners"
+    name = "banners"
+    resource_config = "banners_resource"
+    title = _("Banners")
+    menu_label = _("Banners")
+    category = _("Site management")
+    pid_path = "id"
+    icon = "newspaper"
+
+    display_search = True
+    display_delete = True
+    display_create = True
+    display_edit = True
+
+    item_field_list = {
+        "id": {"text": _("Id"), "order": 1, "width": 1},
+        "start_datetime": {"text": _("Start time (UTC)"), "order": 2, "width": 2},
+        "end_datetime": {"text": _("End time (UTC)"), "order": 3, "width": 2},
+        "message": {"text": _("Message"), "order": 4, "width": 7},
+        "active": {"text": _("Active"), "order": 5, "width": 1},
+        "url_path": {"text": _("URL path"), "order": 6, "width": 2},
+        "category": {"text": _("Category"), "order": 7, "width": 1},
+    }
+
+    create_view_name = "banner_create"
+
+    search_config_name = "BANNERS_SEARCH"
+    search_sort_config_name = "BANNERS_SORT_OPTIONS"
+
+
+common_form_fields = {
+    "start_datetime": {
+        "order": 1,
+        "text": _("Start time"),
+        "description": _(
+            "Date/time to make the banner active. "
+            "Input format: yyyy-mm-dd hh:mm:ss. "
+            "Set to future date/time to delay the banner. "
+            "Note: specify time in UTC time standard."
+        ),
+        "placeholder": _("YYYY-MM-DD hh:mm:ss"),
+    },
+    "end_datetime": {
+        "order": 2,
+        "text": _("End time"),
+        "description": _(
+            "Date/time to make the banner inactive. "
+            "Input format: yyyy-mm-dd hh:mm:ss.  An empty value makes "
+            "the banner active until manually disabled via the active flag. "
+            "Note: specify time in UTC time standard."
+        ),
+        "placeholder": _("YYYY-MM-DD hh:mm:ss"),
+    },
+    "message": {
+        "order": 3,
+        "text": _("Message"),
+        "description": _(
+            "Message to be displayed on the banner. HTML format is supported."
+        ),
+        "rows": 10,
+    },
+    "url_path": {
+        "order": 4,
+        "text": _("URL path"),
+        "description": _(
+            "URL path prefix (including the first /) to define where "
+            "the message will be active on the site. For "
+            "example, if you enter `/records`, any URL starting with "
+            "`/records` will return an active banner (`/records`, "
+            "`/records/1234`, etc.). An empty value makes the banner "
+            "active for any URL."
+        ),
+    },
+    "category": {
+        "order": 5,
+        "text": _("Category"),
+        "description": _(
+            "Banner category. `Info` option displays a blue banner. "
+            "`Warning` option displays an orange banner. "
+            "`Other` option displays a gray banner."
+        ),
+        "options": [
+            {"title_l10n": "Info", "id": "info"},
+            {"title_l10n": "Warning", "id": "warning"},
+            {"title_l10n": "Other", "id": "other"},
+        ],
+        "placeholder": "Select a category",
+    },
+    "active": {
+        "order": 6,
+        "text": _("Active"),
+        "description": _(
+            "Tick it to activate the banner: banner will be "
+            "displayed according to start/end times. If not "
+            "activated, start/end times will be ignored."
+        ),
+    },
+}
+
+
+class BannerEditView(AdminResourceEditView):
+    """Configuration for Banner edit view."""
+
+    name = "banner_edit"
+    url = "/banners/<pid_value>/edit"
+    resource_config = "banners_resource"
+    pid_path = "id"
+    api_endpoint = "/banners"
+    title = _("Edit Banner")
+
+    list_view_name = "banners"
+
+    form_fields = {
+        **common_form_fields,
+        "created": {"order": 7},
+        "updated": {"order": 8},
+    }
+
+
+class BannerCreateView(AdminResourceCreateView):
+    """Configuration for Banner create view."""
+
+    name = "banner_create"
+    url = "/banners/create"
+    resource_config = "banners_resource"
+    pid_path = "id"
+    api_endpoint = "/banners"
+    title = _("Create Banner")
+
+    list_view_name = "banners"
+
+    form_fields = {
+        **common_form_fields,
+    }
+
+
+class BannerDetailView(AdminResourceDetailView):
+    """Admin banner detail view."""
+
+    url = "/banners/<pid_value>"
+    api_endpoint = "/banners"
+    name = "banner-details"
+    resource_config = "banners_resource"
+    title = _("Banner Details")
+
+    display_delete = True
+    display_edit = True
+
+    list_view_name = "banners"
+    pid_path = "id"
+
+    item_field_list = {
+        "start_datetime": {"text": _("Start time"), "order": 1},
+        "end_datetime": {"text": _("End time"), "order": 2},
+        "message": {"text": _("Message"), "order": 3},
+        "url_path": {"text": _("URL path"), "order": 4},
+        "category": {"text": _("Category"), "order": 5},
+        "active": {"text": _("Active"), "order": 6},
+        "created": {"text": _("Created"), "order": 7},
+        "updated": {"text": _("Updated"), "order": 8},
+    }

invenio_banners/alembic/5e02314da32e_create_invenio_banners_db_table.py

@@ -0,0 +1,43 @@
+#
+# This file is part of Invenio.
+# Copyright (C) 2016-2018 CERN.
+#
+# Invenio is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Create invenio-banners db table."""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "5e02314da32e"
+down_revision = "e40d93d99040"
+branch_labels = ()
+depends_on = None
+
+
+def upgrade():
+    """Upgrade database."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "banners",
+        sa.Column("created", sa.DateTime(), nullable=False),
+        sa.Column("updated", sa.DateTime(), nullable=False),
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("message", sa.Text(), nullable=False),
+        sa.Column("url_path", sa.String(length=255), nullable=True),
+        sa.Column("category", sa.String(length=20), nullable=False),
+        sa.Column("start_datetime", sa.DateTime(), nullable=False),
+        sa.Column("end_datetime", sa.DateTime(), nullable=True),
+        sa.Column("active", sa.Boolean(name="active"), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_banners")),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    """Downgrade database."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("banners")
+    # ### end Alembic commands ###

invenio_banners/alembic/e40d93d99040_create_invenio_banners_branch.py

@@ -0,0 +1,27 @@
+#
+# This file is part of Invenio.
+# Copyright (C) 2016-2018 CERN.
+#
+# Invenio is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Create invenio-banners branch."""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "e40d93d99040"
+down_revision = None
+branch_labels = ("invenio_banners",)
+depends_on = "dbdbc1b19cf2"
+
+
+def upgrade():
+    """Upgrade database."""
+    pass
+
+
+def downgrade():
+    """Downgrade database."""
+    pass

invenio_banners/config.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2020-2023 CERN.
+# Copyright (C) 2024 KTH Royal Institute of Technology.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Configuration variables."""
+
+from invenio_i18n import lazy_gettext as _
+
+from invenio_banners.utils import style_category
+
+BANNERS_CATEGORIES = [
+    ("info", _("Info")),
+    ("warning", _("Warning")),
+    ("other", _("Other")),
+]
+"""Categories to define different types of messages. List of (id, label)."""
+
+BANNERS_CATEGORIES_TO_STYLE = style_category
+"""Function to transform the banner category to a specific Semantic-UI class."""
+
+BANNERS_SEARCH = {
+    "facets": [],
+    "sort": [
+        "url_path",
+        "start_datetime",
+        "end_datetime",
+        "active",
+    ],
+}
+"""Banner search configuration (i.e list of banners)"""
+
+BANNERS_SORT_OPTIONS = {
+    "url_path": dict(
+        title=_("URL path"),
+        fields=["url_path"],
+    ),
+    "start_datetime": dict(
+        title=_("Start DateTime"),
+        fields=["start_datetime"],
+    ),
+    "end_datetime": dict(
+        title=_("End DateTime"),
+        fields=["end_datetime"],
+    ),
+    "active": dict(
+        title=_("Active"),
+        fields=["active"],
+    ),
+}
+"""Definitions of available Banners sort options. """

invenio_banners/ext.py

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2020-2023 CERN.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Invenio extension app."""
+
+from flask import Blueprint
+
+from . import config
+from .resources import BannerResource, BannerResourceConfig
+from .services import BannerService, BannerServiceConfig
+from .utils import get_active_banners_for_request
+
+blueprint = Blueprint(
+    "invenio_banners",
+    __name__,
+    template_folder="templates",
+    static_folder="static",
+)
+
+
+class InvenioBanners(object):
+    """Invenio-Banners extension."""
+
+    def __init__(self, app=None):
+        """Extension initialization."""
+        if app:
+            self.init_app(app)
+
+    def init_app(self, app):
+        """Flask application initialization."""
+        self.init_config(app)
+        self.init_services(app)
+        self.init_resources(app)
+        app.extensions["invenio-banners"] = self
+        app.register_blueprint(blueprint)
+        app.jinja_env.globals["get_active_banners"] = get_active_banners_for_request
+        app.jinja_env.filters["style_banner_category"] = app.config[
+            "BANNERS_CATEGORIES_TO_STYLE"
+        ]
+
+    def init_config(self, app):
+        """Initialize configuration."""
+        for k in dir(config):
+            if k.startswith("BANNERS_"):
+                app.config.setdefault(k, getattr(config, k))
+
+    def init_services(self, app):
+        """Initialize the services for banners."""
+        self.banners_service = BannerService(config=BannerServiceConfig)
+
+    def init_resources(self, app):
+        """Initialize the resources for banners."""
+        self.banners_resource = BannerResource(
+            service=self.banners_service,
+            config=BannerResourceConfig,
+        )

invenio_banners/proxies.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2022 CERN.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Proxies for accessing the current Banners extension."""
+
+from flask import current_app
+from werkzeug.local import LocalProxy
+
+current_banners = LocalProxy(lambda: current_app.extensions["invenio-banners"])
+"""Proxy for the instantiated Banners extension."""
+
+current_banners_service = LocalProxy(
+    lambda: current_app.extensions["invenio-banners"].banners_service
+)
+"""Proxy for the currently instantiated banners service."""

invenio_banners/records/__init__.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2020-2023 CERN.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Records directory."""
+
+
+from .models import BannerModel
+
+__all__ = ("BannerModel",)

invenio_banners/records/models.py

@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2020-2023 CERN.
+# Copyright (C) 2024-2025 Graz University of Technology.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Models."""
+
+from datetime import datetime, timezone
+
+import sqlalchemy as sa
+from flask import current_app
+from invenio_db import db
+from sqlalchemy import or_
+from sqlalchemy.sql import text
+from sqlalchemy_utils.models import Timestamp
+
+from ..resources.errors import BannerNotExistsError
+
+
+class BannerModel(db.Model, Timestamp):
+    """Defines a message to show to users."""
+
+    __tablename__ = "banners"
+
+    id = db.Column(db.Integer, primary_key=True)
+
+    message = db.Column(db.Text, nullable=False)
+    """The message content."""
+
+    url_path = db.Column(db.String(255), nullable=True)
+    """Define in which URL /path the message will be visible."""
+
+    category = db.Column(db.String(20), nullable=False)
+    """Category of the message, for styling messages per category."""
+
+    start_datetime = db.Column(db.DateTime, nullable=False, default=datetime.utcnow)
+    """Start date and time (UTC), can be immediate or delayed."""
+
+    end_datetime = db.Column(db.DateTime, nullable=True)
+    """End date and time (UTC), must be after `start` or forever if null."""
+
+    active = db.Column(db.Boolean(name="active"), nullable=False, default=True)
+    """Defines if the message is active, only one at the same time."""
+
+    @classmethod
+    def create(cls, data):
+        """Create a new banner."""
+        _categories = [t[0] for t in current_app.config["BANNERS_CATEGORIES"]]
+        assert data.get("category") in _categories
+
+        with db.session.begin_nested():
+            obj = cls(
+                message=data.get("message"),
+                category=data.get("category"),
+                url_path=data.get("url_path"),
+                start_datetime=data.get("start_datetime"),
+                end_datetime=data.get("end_datetime"),
+                active=data.get("active"),
+            )
+            db.session.add(obj)
+
+        return obj
+
+    @classmethod
+    def update(cls, data, id):
+        """Update an existing banner."""
+        with db.session.begin_nested():
+            # NOTE:
+            # with db.session.get(cls, id) the model itself would be
+            # returned and this classmethod would be called
+            db.session.query(cls).filter_by(id=id).update(data)
+
+    @classmethod
+    def get(cls, id):
+        """Get banner by its id."""
+        if banner := db.session.get(cls, id):
+            return banner
+
+        raise BannerNotExistsError(id)
+
+    @classmethod
+    def delete(cls, banner):
+        """Delete banner by its id."""
+        with db.session.begin_nested():
+            db.session.delete(banner)
+
+    @classmethod
+    def get_active(cls, url_path):
+        """Return active banners."""
+        now = datetime.now(timezone.utc).replace(tzinfo=None)
+
+        query = (
+            db.session.query(cls)
+            .filter(cls.active.is_(True))
+            .filter(cls.start_datetime <= now)
+            .filter((cls.end_datetime.is_(None)) | (now <= cls.end_datetime))
+        )
+
+        # filter by url_path
+        active_banners = query.filter(
+            sa.or_(
+                cls.url_path.is_(None),
+                sa.literal(url_path).startswith(cls.url_path),
+            )
+        )
+
+        return active_banners.all()
+
+    @classmethod
+    def search(cls, search_params, filters=None):
+        """Filter banners accordingly to query params."""
+        if filters:
+            filtered = db.session.query(BannerModel).filter(or_(*filters))
+        else:
+            filtered = db.session.query(BannerModel).filter()
+
+        banners = filtered.order_by(
+            search_params["sort_direction"](text(",".join(search_params["sort"])))
+        ).paginate(
+            page=search_params["page"],
+            per_page=search_params["size"],
+            error_out=False,
+        )
+
+        return banners
+
+    @classmethod
+    def disable_expired(cls):
+        """Disable any old still active messages to keep everything clean."""
+        now = datetime.now(timezone.utc).replace(tzinfo=None)
+
+        query = (
+            db.session.query(cls)
+            .filter(cls.active.is_(True))
+            .filter(cls.end_datetime.isnot(None))
+            .filter(cls.end_datetime < now)
+        )
+
+        for old in query.all():
+            old.active = False

invenio_banners/resources/__init__.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2022 CERN.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Invenio Resources module to create REST APIs."""
+
+from .config import BannerResourceConfig
+from .resource import BannerResource
+
+__all__ = (
+    "BannerResource",
+    "BannerResourceConfig",
+)

invenio_banners/resources/config.py

@@ -0,0 +1,51 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2022-2025 CERN.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Banner Resource Configuration."""
+
+import marshmallow as ma
+from flask_resources import JSONDeserializer, RequestBodyParser
+from invenio_records_resources.resources import (
+    RecordResourceConfig,
+    SearchRequestArgsSchema,
+)
+
+
+class BannerServerSearchRequestArgsSchema(SearchRequestArgsSchema):
+    """Banner request parameters."""
+
+    sort_direction = ma.fields.Str()
+    active = ma.fields.Bool()
+    url_path = ma.fields.Str()
+
+
+class BannerResourceConfig(RecordResourceConfig):
+    """Banner resource config."""
+
+    # Blueprint configuration
+    blueprint_name = "banners"
+    url_prefix = "/banners"
+    routes = {
+        "item": "/<banner_id>",
+        "list": "/",
+    }
+
+    request_view_args = {
+        "banner_id": ma.fields.String(),
+    }
+
+    request_search_args = BannerServerSearchRequestArgsSchema
+
+    request_body_parsers = {"application/json": RequestBodyParser(JSONDeserializer())}
+    default_content_type = "application/json"
+
+    response_handlers = {
+        "application/vnd.inveniordm.v1+json": RecordResourceConfig.response_handlers[
+            "application/json"
+        ],
+        **RecordResourceConfig.response_handlers,
+    }