Initial commit

Author: nixjdm

.flake8

@@ -0,0 +1,5 @@
+[flake8]
+ignore = E203, E266, E501, W503, F403, F401
+max-line-length = 89
+max-complexity = 18
+# select = B,C,E,F,W,T4,B9

.gitignore

@@ -0,0 +1,12 @@
+dist
+build
+.coverage
+.tox
+flymd*
+*.pyc
+*.pyo
+*.egg-info
+*~
+*#
+.#*
+*.org

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/ambv/black
+    rev: "22.10.0"
+    hooks:
+      - id: black
+  - repo: https://github.com/asottile/reorder_python_imports
+    rev: "v3.9.0"
+    hooks:
+      - id: reorder-python-imports
+  - repo: https://github.com/PyCQA/flake8
+    rev: "5.0.4"
+    hooks:
+      - id: flake8
+        language_version: python3
+        additional_dependencies: [
+          flake8-bugbear,
+        ]

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, Terminal Labs Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,32 @@
+## Lektor Debug
+
+This Plugin provides a `{% debug %}` template tag that will render helpful debugging information in a template. To use, simply add this tag in a template, and run lektor server in development mode with `LEKTOR_DEV=1 lektor server`.
+
+This plugin replaces Lektor's built-in, optional `{% debug %}` tag from Jinja2's Debug Extension. That tag is completely superceded by this plugins, so we just replace it.
+
+This plugins tag can also be left in with no ill-effects. Unless the environment variable `LEKTOR_DEV=1` is set, `{% debug %}` will be a noop and return an empty string, unlike Lektor's current behavior which, since Jinja2's Debug Extension would not be added, would raise a `TemplateSyntaxError`.
+
+### `{% debug %}` contents
+
+This tag automatically renders as a collapsed `<detail>` html element, so it is minimally invasive unless you need it. When expanded, it will show a Python-ish dict with keys for:
+
+- All fields available on `this`
+- The complete `dir(this)`, which shows it's native attributes and methods (different from the above)
+- All flowblocks and their fields
+- All current template context, exactly like Jinja2's Debug Extension
+- All available template filters, exactly like Jinja2's Debug Extension
+- All available template tests, exactly like Jinja2's Debug Extension
+
+The top-level keys are meant to quickly tell you what that piece of data is, but do not necessarily correspond to an available key in a real Python dict. For example, `this.fields` is not a key in any Lektor Python dict, but it's hopefully clear what this represents.
+
+Flowblocks are listed as `this.<flowblock name>.blocks`, which is how you would access them in a template. Each flow field will present a list of dicts of all blocks' fields and their values.
+
+This debug info is presented as a code block, ran through Lektor's markdown processor. Since that is the case, if you have [Lektor Markdown Highlighter](https://www.getlektor.com/plugins/lektor-markdown-highlighter/) installed and configured, this will also use the syntax highlighting for Python.
+
+### Additional Template Context
+
+This plugin also adds the following template variables globally:
+
+- `{{ dir }}` Python's `dir` builtin
+- `{{ str }}` Python's `str` builtin
+- `{{ type }}` Python's `type` builtin

lektor_debug.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+import os
+import pprint
+
+from jinja2.ext import DebugExtension
+from markupsafe import Markup
+
+from lektor.pluginsystem import Plugin
+from lektor.markdown import Markdown
+from lektor.types.flow import FlowDescriptor
+
+class LektorDebugExtension(DebugExtension):
+    """Jinja extension for Lektor to replace Jinja's native Debug extension"""
+    def _render(self, context) -> str:
+        if not os.environ.get("LEKTOR_DEV") == "1":
+            return ""
+
+        raw = {}
+
+        this = context.get('this')  # not always present
+        if this:
+            data = getattr(this, '_data', None)
+            if data:
+                raw['this.fields'] = data
+                for k, v in data.items():
+                    if isinstance(v, FlowDescriptor):
+                        raw[f"flow: this.{k}.blocks"] = v._blocks
+            raw['dir(this)'] = dir(this)
+
+        raw.update({
+            "context": context.get_all(),
+            "filters": sorted(self.environment.filters.keys()),
+            "tests": sorted(self.environment.tests.keys()),
+        })
+        md_str = f"""\
+```python
+{pprint.pformat(raw, depth=3, compact=True)}
+```
+"""
+        options = {'type': 'markdown'}
+        record = context['this']
+        md = Markdown(md_str, record, options)
+        return Markup(f"<details><summary>DEBUG INFO -></summary>{md}</details>")
+
+
+class DebugPlugin(Plugin):
+    name = 'Lektor Debug'
+    description = 'A Lektor Plugin for Debugging Help'
+
+    # TODO run this on all builds. on_before_build_all seems to sometimes error
+    # with `TemplateSyntaxError: Encountered unknown tag 'debug'` and sometimes not.
+    # def on_before_build_all(self, builder, **extra):
+    def on_server_spawn(self, **extras):
+        if "jinja2.ext.DebugExtension" in self.env.jinja_env.extensions:
+            del self.env.jinja_env.extensions["jinja2.ext.DebugExtension"]
+
+        # Always add the extension so the tag always works. It is just a noop
+        # unless LEKTOR_DEV==1. This let's us keep the tag in all the time.
+        self.env.jinja_env.add_extension(LektorDebugExtension)
+
+    def on_setup_env(self, **extra):
+        self.env.jinja_env.globals['str'] = str
+        self.env.jinja_env.globals['dir'] = dir
+        self.env.jinja_env.globals['type'] = type

setup.py

@@ -0,0 +1,38 @@
+import ast
+import io
+import re
+
+from setuptools import setup, find_packages
+
+with io.open('README.md', 'rt', encoding="utf8") as f:
+    readme = f.read()
+
+_description_re = re.compile(r'description\s+=\s+(?P<description>.*)')
+
+with open('lektor_debug.py', 'rb') as f:
+    description = str(ast.literal_eval(_description_re.search(
+        f.read().decode('utf-8')).group(1)))
+
+setup(
+    author='Joseph Nix',
+    author_email='[email protected]',
+    description=description,
+    keywords='Lektor plugin',
+    license='BSD-3-Clause',
+    long_description=readme,
+    long_description_content_type='text/markdown',
+    name='lektor-debug',
+    packages=find_packages(),
+    py_modules=['lektor_debug'],
+    url='https://github.com/terminal-labs/lektor-debug',
+    version='0.1',
+    classifiers=[
+        'Framework :: Lektor',
+        'Environment :: Plugins',
+    ],
+    entry_points={
+        'lektor.plugins': [
+            'debug = lektor_debug:DebugPlugin',
+        ]
+    }
+)