_pages.py

import collections
import importlib
import os
import re
import sys
from fnmatch import fnmatch
from pathlib import Path
from os.path import isfile, join
from urllib.parse import parse_qs

import flask

from . import _validate
from ._utils import AttributeDict
from ._get_paths import get_relative_path
from ._callback_context import context_value
from ._get_app import get_app


CONFIG = AttributeDict()
PAGE_REGISTRY = collections.OrderedDict()


def _infer_image(module):
    """
    Return:
    - A page specific image: `assets/<module>.<extension>` is used, e.g. `assets/weekly_analytics.png`
    - A generic app image at `assets/app.<extension>`
    - A logo at `assets/logo.<extension>`
    """
    assets_folder = CONFIG.assets_folder
    valid_extensions = ["apng", "avif", "gif", "jpeg", "jpg", "png", "svg", "webp"]
    page_id = module.split(".")[-1]
    files_in_assets = []

    if os.path.exists(assets_folder):
        files_in_assets = [
            f for f in os.listdir(assets_folder) if isfile(join(assets_folder, f))
        ]
    app_file = None
    logo_file = None
    for fn in files_in_assets:
        fn_without_extension, _, extension = fn.partition(".")
        if extension.lower() in valid_extensions:
            if (
                fn_without_extension == page_id
                or fn_without_extension == page_id.replace("_", "-")
            ):
                return fn

            if fn_without_extension == "app":
                app_file = fn

            if fn_without_extension == "logo":
                logo_file = fn

    if app_file:
        return app_file

    return logo_file


def _module_name_to_page_name(module_name):
    return module_name.split(".")[-1].replace("_", " ").capitalize()


def _infer_path(module_name, template):
    if template is None:
        if CONFIG.pages_folder:
            pages_module = str(Path(CONFIG.pages_folder).name)
            path = (
                module_name.split(pages_module)[-1]
                .replace("_", "-")
                .replace(".", "/")
                .lower()
            )
        else:
            path = module_name.replace("_", "-").replace(".", "/").lower()
    else:
        # replace the variables in the template with "none" to create a default path if
        # no path is supplied
        path = re.sub("<.*?>", "none", template)
    path = "/" + path if not path.startswith("/") else path
    return path


def _module_name_is_package(module_name):
    return (
        module_name in sys.modules
        and Path(sys.modules[module_name].__file__).name == "__init__.py"
    )


def _path_to_module_name(path):
    return str(path).replace(".py", "").strip(os.sep).replace(os.sep, ".")


def _infer_module_name(page_path):
    relative_path = page_path.split(CONFIG.pages_folder)[-1]
    module = _path_to_module_name(relative_path)
    proj_root = flask.helpers.get_root_path(CONFIG.name)
    if CONFIG.pages_folder.startswith(proj_root):
        parent_path = CONFIG.pages_folder[len(proj_root) :]
    else:
        parent_path = CONFIG.pages_folder
    parent_module = _path_to_module_name(parent_path)

    module_name = f"{parent_module}.{module}"
    if _module_name_is_package(CONFIG.name):
        # Only prefix with CONFIG.name when it's an imported package name
        module_name = f"{CONFIG.name}.{module_name}"
    return module_name


def _parse_query_string(search):
    if search and len(search) > 0 and search[0] == "?":
        search = search[1:]
    else:
        return {}

    parsed_qs = {}
    for (k, v) in parse_qs(search).items():
        v = v[0] if len(v) == 1 else v
        parsed_qs[k] = v
    return parsed_qs


def _parse_path_variables(pathname, path_template):
    """
    creates the dict of path variables passed to the layout
    e.g. path_template= "/asset/<asset_id>"
         if pathname provided by the browser is "/assets/a100"
         returns **{"asset_id": "a100"}
    """

    # parse variable definitions e.g. <var_name> from template
    # and create pattern to match
    wildcard_pattern = re.sub("<.*?>", "*", path_template)
    var_pattern = re.sub("<.*?>", "(.*)", path_template)

    # check that static sections of the pathname match the template
    if not fnmatch(pathname, wildcard_pattern):
        return None

    # parse variable names e.g. var_name from template
    var_names = re.findall("<(.*?)>", path_template)

    # parse variables from path
    variables = re.findall(var_pattern, pathname)
    variables = variables[0] if isinstance(variables[0], tuple) else variables

    return dict(zip(var_names, variables))


def _create_redirect_function(redirect_to):
    def redirect():
        return flask.redirect(redirect_to, code=301)

    return redirect


def _set_redirect(redirect_from, path):
    app = get_app()
    if redirect_from and len(redirect_from):
        for redirect in redirect_from:
            fullname = app.get_relative_path(redirect)
            app.server.add_url_rule(
                fullname,
                fullname,
                _create_redirect_function(app.get_relative_path(path)),
            )


def register_page(
    module,
    path=None,
    path_template=None,
    name=None,
    order=None,
    title=None,
    description=None,
    image=None,
    image_url=None,
    redirect_from=None,
    layout=None,
    **kwargs,
):
    """
    Assigns the variables to `dash.page_registry` as an `OrderedDict`
    (ordered by `order`).

    `dash.page_registry` is used by `pages_plugin` to set up the layouts as
    a multi-page Dash app. This includes the URL routing callbacks
    (using `dcc.Location`) and the HTML templates to include title,
    meta description, and the meta description image.

    `dash.page_registry` can also be used by Dash developers to create the
    page navigation links or by template authors.

    - `module`:
       The module path where this page's `layout` is defined. Often `__name__`.

    - `path`:
       URL Path, e.g. `/` or `/home-page`.
       If not supplied, will be inferred from the `path_template` or `module`,
       e.g. based on path_template: `/asset/<asset_id` to `/asset/none`
       e.g. based on module: `pages.weekly_analytics` to `/weekly-analytics`

    - `relative_path`:
        The path with `requests_pathname_prefix` prefixed before it.
        Use this path when specifying local URL paths that will work
        in environments regardless of what `requests_pathname_prefix` is.
        In some deployment environments, like Dash Enterprise,
        `requests_pathname_prefix` is set to the application name,
        e.g. `my-dash-app`.
        When working locally, `requests_pathname_prefix` might be unset and
        so a relative URL like `/page-2` can just be `/page-2`.
        However, when the app is deployed to a URL like `/my-dash-app`, then
        `relative_path` will be `/my-dash-app/page-2`.

    - `path_template`:
       Add variables to a URL by marking sections with <variable_name>. The layout function
       then receives the <variable_name> as a keyword argument.
       e.g. path_template= "/asset/<asset_id>"
            then if pathname in browser is "/assets/a100" then layout will receive **{"asset_id":"a100"}

    - `name`:
       The name of the link.
       If not supplied, will be inferred from `module`,
       e.g. `pages.weekly_analytics` to `Weekly analytics`

    - `order`:
       The order of the pages in `page_registry`.
       If not supplied, then the filename is used and the page with path `/` has
       order `0`

    - `title`:
       (string or function) The name of the page <title>. That is, what appears in the browser title.
       If not supplied, will use the supplied `name` or will be inferred by module,
       e.g. `pages.weekly_analytics` to `Weekly analytics`

    - `description`:
       (string or function) The <meta type="description"></meta>.
       If not supplied, then nothing is supplied.

    - `image`:
       The meta description image used by social media platforms.
       If not supplied, then it looks for the following images in `assets/`:
        - A page specific image: `assets/<module>.<extension>` is used, e.g. `assets/weekly_analytics.png`
        - A generic app image at `assets/app.<extension>`
        - A logo at `assets/logo.<extension>`
        When inferring the image file, it will look for the following extensions:
        APNG, AVIF, GIF, JPEG, JPG, PNG, SVG, WebP.

    -  `image_url`:
       Overrides the image property and sets the `<image>` meta tag to the provided image URL.

    - `redirect_from`:
       A list of paths that should redirect to this page.
       For example: `redirect_from=['/v2', '/v3']`

    - `layout`:
       The layout function or component for this page.
       If not supplied, then looks for `layout` from within the supplied `module`.

    - `**kwargs`:
       Arbitrary keyword arguments that can be stored

    ***

    `page_registry` stores the original property that was passed in under
    `supplied_<property>` and the coerced property under `<property>`.
    For example, if this was called:
    ```
    register_page(
        'pages.historical_outlook',
        name='Our historical view',
        custom_key='custom value'
    )
    ```
    Then this will appear in `page_registry`:
    ```
    OrderedDict([
        (
            'pages.historical_outlook',
            dict(
                module='pages.historical_outlook',

                supplied_path=None,
                path='/historical-outlook',

                supplied_name='Our historical view',
                name='Our historical view',

                supplied_title=None,
                title='Our historical view'

                supplied_layout=None,
                layout=<function pages.historical_outlook.layout>,

                custom_key='custom value'
            )
        ),
    ])
    ```
    """
    if context_value.get().get("ignore_register_page"):
        return

    _validate.validate_use_pages(CONFIG)

    page = dict(
        module=_validate.validate_module_name(module),
        supplied_path=path,
        path_template=path_template,
        path=path if path is not None else _infer_path(module, path_template),
        supplied_name=name,
        name=name if name is not None else _module_name_to_page_name(module),
    )
    page.update(
        supplied_title=title,
        title=(title if title is not None else page["name"]),
    )
    page.update(
        description=description if description else "",
        order=order,
        supplied_order=order,
        supplied_layout=layout,
        **kwargs,
    )
    page.update(
        supplied_image=image,
        image=(image if image is not None else _infer_image(module)),
        image_url=image_url,
    )
    page.update(redirect_from=_set_redirect(redirect_from, page["path"]))

    PAGE_REGISTRY[module] = page

    if page["path_template"]:
        _validate.validate_template(page["path_template"])

    if layout is not None:
        # Override the layout found in the file set during `plug`
        PAGE_REGISTRY[module]["layout"] = layout

    # set home page order
    order_supplied = any(
        p["supplied_order"] is not None for p in PAGE_REGISTRY.values()
    )

    for p in PAGE_REGISTRY.values():
        p["order"] = (
            0 if p["path"] == "/" and not order_supplied else p["supplied_order"]
        )
        p["relative_path"] = get_relative_path(p["path"])

    # Sort numeric orders first, then string orders, then no order,
    # finally by module name for matching orders
    for page in sorted(
        PAGE_REGISTRY.values(),
        key=lambda i: (
            i["order"] is None,  # False (order given) sorts before True
            i["order"] if isinstance(i["order"], (int, float)) else float("inf"),
            str(i["order"]),
            i["module"],
        ),
    ):
        PAGE_REGISTRY.move_to_end(page["module"])


def _path_to_page(path_id):
    path_variables = None
    for page in PAGE_REGISTRY.values():
        if page["path_template"]:
            template_id = page["path_template"].strip("/")
            path_variables = _parse_path_variables(path_id, template_id)
            if path_variables:
                return page, path_variables
        if path_id == page["path"].strip("/"):
            return page, path_variables
    return {}, None


def _page_meta_tags(app):
    start_page, path_variables = _path_to_page(flask.request.path.strip("/"))

    # use the supplied image_url or create url based on image in the assets folder
    image = start_page.get("image", "")
    if image:
        image = app.get_asset_url(image)
    assets_image_url = (
        "".join([flask.request.url_root, image.lstrip("/")]) if image else None
    )
    supplied_image_url = start_page.get("image_url")
    image_url = supplied_image_url if supplied_image_url else assets_image_url

    title = start_page.get("title", app.title)
    if callable(title):
        title = title(**path_variables) if path_variables else title()

    description = start_page.get("description", "")
    if callable(description):
        description = description(**path_variables) if path_variables else description()

    return [
        {"name": "description", "content": description},
        {"property": "twitter:card", "content": "summary_large_image"},
        {"property": "twitter:url", "content": flask.request.url},
        {"property": "twitter:title", "content": title},
        {"property": "twitter:description", "content": description},
        {"property": "twitter:image", "content": image_url or ""},
        {"property": "og:title", "content": title},
        {"property": "og:type", "content": "website"},
        {"property": "og:description", "content": description},
        {"property": "og:image", "content": image_url or ""},
    ]


def _import_layouts_from_pages(pages_folder):
    for root, dirs, files in os.walk(pages_folder):
        dirs[:] = [d for d in dirs if not d.startswith(".") and not d.startswith("_")]
        for file in files:
            if file.startswith("_") or file.startswith(".") or not file.endswith(".py"):
                continue
            page_path = os.path.join(root, file)
            with open(page_path, encoding="utf-8") as f:
                content = f.read()
                if "register_page" not in content:
                    continue

            module_name = _infer_module_name(page_path)
            spec = importlib.util.spec_from_file_location(module_name, page_path)
            page_module = importlib.util.module_from_spec(spec)
            spec.loader.exec_module(page_module)
            sys.modules[module_name] = page_module

            if (
                module_name in PAGE_REGISTRY
                and not PAGE_REGISTRY[module_name]["supplied_layout"]
            ):
                _validate.validate_pages_layout(module_name, page_module)
                PAGE_REGISTRY[module_name]["layout"] = getattr(page_module, "layout")