Skip to content
Permalink
Browse files Browse the repository at this point in the history
Merge pull request #110 from d0c-s4vage/feature/109-extension_warnings
Adds warnings about loading extensions
  • Loading branch information
d0c-s4vage committed Oct 23, 2020
2 parents f5d5f8b + dc5a99b commit 72fe36b
Show file tree
Hide file tree
Showing 12 changed files with 232 additions and 19 deletions.
10 changes: 10 additions & 0 deletions README.md
Expand Up @@ -63,6 +63,8 @@ Usage: lookatme [OPTIONS] [INPUT_FILES]...
lookatme - An interactive, terminal-based markdown presentation tool.
See https://lookatme.readthedocs.io/en/v{{VERSION}} for documentation
Options:
--debug
-l, --log PATH
Expand All @@ -74,6 +76,14 @@ Options:
--live, --live-reload Watch the input filename for modifications
and automatically reload
-s, --safe Do not load any new extensions specified in
the source markdown. Extensions specified
via env var or -e are still loaded
--no-ext-warn Load new extensions specified in the source
markdown without warning
-i, --ignore-ext-failure Ignore load failures of extensions
-e, --exts TEXT A comma-separated list of extension names to
automatically load (LOOKATME_EXTS)
Expand Down
Binary file modified docs/source/_static/lookatme_tour.gif
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
32 changes: 31 additions & 1 deletion docs/source/getting_started.rst
Expand Up @@ -24,6 +24,8 @@ The ``lookatme`` CLI has a few options to control it's behavior:
lookatme - An interactive, terminal-based markdown presentation tool.
See https://lookatme.readthedocs.io/en/v{{VERSION}} for documentation
Options:
--debug
-l, --log PATH
Expand All @@ -35,6 +37,14 @@ The ``lookatme`` CLI has a few options to control it's behavior:
--live, --live-reload Watch the input filename for modifications
and automatically reload
-s, --safe Do not load any new extensions specified in
the source markdown. Extensions specified
via env var or -e are still loaded
--no-ext-warn Load new extensions specified in the source
markdown without warning
-i, --ignore-ext-failure Ignore load failures of extensions
-e, --exts TEXT A comma-separated list of extension names to
automatically load (LOOKATME_EXTS)
Expand All @@ -58,11 +68,31 @@ are possible:
:alt: Live Updates

``-e EXT_NAME1,EXT_NAME2`` / ``--exts EXT_NAME1,EXT_NAME2``
^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Allows a comma-separated list of extension names to be pre-loaded into lookatme
without requring them to be declared in the Markdown source.

``-s`` / ``--safe``
^^^^^^^^^^^^^^^^^^^

Do **NOT** load any new extensions specified in the markdown (ignore them). New
extensions are extensions that have not manually been allowed via the ``-e``
argument or the ``LOOKATME_EXTS`` environment variable.

``--no-ext-warn``
^^^^^^^^^^^^^^^^^

Do not warn about new extensions that are to-be-loaded that are specified in
the source markdown. New extensions are extensions that have not manually been
allowed via the ``-e`` argument or the ``LOOKATME_EXTS`` environment variable.

``-i``
^^^^^^

Ignore failure loading extensions. This does not ignore warnings, but ignores
any hard-errors during import, such as ``ImportError``.


``--single`` / ``--one``
^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down
8 changes: 8 additions & 0 deletions examples/calendar_contrib/lookatme/contrib/calendar.py
Expand Up @@ -12,6 +12,14 @@
from lookatme.exceptions import IgnoredByContrib


def user_warnings():
"""No warnings exist for this extension. Anything you want to warn the
user about, such as security risks in processing untrusted markdown, should
go here.
"""
return []


def render_code(token, body, stack, loop):
lang = token["lang"] or ""
if lang != "calendar":
Expand Down
15 changes: 8 additions & 7 deletions examples/tour.md
Expand Up @@ -3,18 +3,19 @@ title: lookatme Tour
date: 2020-10-09
author: James Johnson
extensions:
- terminal
- qrcode
- image_ueberzug
styles:
style: solarized-dark
style: monokai
table:
column_spacing: 5
column_spacing: 15
margin:
top: 3
bottom: 0
padding:
top: 1
bottom: 1
top: 3
bottom: 3
---

# Markdown Support: Inline
Expand Down Expand Up @@ -170,16 +171,16 @@ docker run --rm -it ubuntu:18.04

# Live Editing

When run with the `--live` option, lookatme watches for file changes and
auto-reloads the source markdown
Hello from vim! The `--live` flag makes lookatme watch the source input
for file changes and auto-reloads the slides.

---

# Live Editing: Including Styles!

```python
def a_function(test):
print "Hello again from vim"
print "Hello again from vim again"
```

| h1 | h2 | h3 |
Expand Down
29 changes: 28 additions & 1 deletion lookatme/__main__.py
Expand Up @@ -58,6 +58,27 @@
is_flag=True,
default=False,
)
@click.option(
"-s",
"--safe",
help="Do not load any new extensions specified in the source markdown. "
"Extensions specified via env var or -e are still loaded",
is_flag=True,
default=False,
)
@click.option(
"--no-ext-warn",
help="Load new extensions specified in the source markdown without warning",
is_flag=True,
default=False,
)
@click.option(
"-i",
"--ignore-ext-failure",
help="Ignore load failures of extensions",
is_flag=True,
default=False,
)
@click.option(
"-e",
"--exts",
Expand All @@ -82,8 +103,11 @@
nargs=-1,
)
def main(debug, log_path, theme, code_style, dump_styles,
input_files, live_reload, extensions, single_slide):
input_files, live_reload, extensions, single_slide, safe, no_ext_warn,
ignore_ext_failure):
"""lookatme - An interactive, terminal-based markdown presentation tool.
See https://lookatme.readthedocs.io/en/v{{VERSION}} for documentation
"""
if debug:
lookatme.config.LOG = lookatme.log.create_log(log_path)
Expand All @@ -102,6 +126,9 @@ def main(debug, log_path, theme, code_style, dump_styles,
live_reload=live_reload,
single_slide=single_slide,
preload_extensions=preload_exts,
safe=safe,
no_ext_warn=no_ext_warn,
ignore_ext_failure=ignore_ext_failure,
)

if dump_styles:
Expand Down
22 changes: 22 additions & 0 deletions lookatme/ascii_art.py
@@ -0,0 +1,22 @@
"""
Misc ASCII art
"""

WARNING = r"""
_mBma
sQf "QL
jW( -$g.
jW' -$m,
.y@' _aa. 4m,
.mD` ]QQWQ. 4Q,
_mP` ]QQQQ ?Q/
_QF )WQQ@ ?Qc
<QF QQQF )Qa
jW( QQQf "QL
jW' ]H8' -Q6.
.y@' _as. -$m.
.m@` ]QQWQ. -4m,
_mP` -?$8! 4Q,
mE $m
?$gyygggggggggwywgyygggggggygggggD(
"""
49 changes: 43 additions & 6 deletions lookatme/contrib/__init__.py
Expand Up @@ -8,41 +8,78 @@
import contextlib


import lookatme.ascii_art
from lookatme.exceptions import IgnoredByContrib
import lookatme.prompt
from . import terminal
from . import file_loader


CONTRIB_MODULES = [
terminal,
file_loader,
]
CONTRIB_MODULES = []


def load_contribs(contrib_names):
def validate_extension_mod(ext_name, ext_mod):
"""Validate the extension, returns an array of warnings associated with the
module
"""
res = []
if not hasattr(ext_mod, "user_warnings"):
res.append("'user_warnings' is missing. Extension is not able to "
"provide user warnings.")
else:
res += ext_mod.user_warnings()

return res


def load_contribs(contrib_names, safe_contribs, ignore_load_failure=False):
"""Load all contrib modules specified by ``contrib_names``. These should
all be namespaced packages under the ``lookatmecontrib`` namespace. E.g.
``lookatmecontrib.calendar`` would be an extension provided by a
contrib module, and would be added to an ``extensions`` list in a slide's
YAML header as ``calendar``.
``safe_contribs`` is a set of contrib names that are manually provided
by the user by the ``-e`` flag or env variable of extensions to auto-load.
"""
if contrib_names is None:
return

errors = []
all_warnings = []
for contrib_name in contrib_names:
module_name = f"lookatme.contrib.{contrib_name}"
try:
mod = __import__(module_name, fromlist=[contrib_name])
CONTRIB_MODULES.append(mod)
except Exception as e:
if ignore_load_failure:
continue
errors.append(str(e))
else:
if contrib_name not in safe_contribs:
ext_warnings = validate_extension_mod(contrib_name, mod)
if len(ext_warnings) > 0:
all_warnings.append((contrib_name, ext_warnings))
CONTRIB_MODULES.append(mod)

if len(errors) > 0:
raise Exception(
"Error loading one or more extensions:\n\n" + "\n".join(errors),
)

if len(all_warnings) == 0:
return

print("\nExtension-provided user warnings:")
for ext_name, ext_warnings in all_warnings:
print("\n {!r}:\n".format(ext_name))
for ext_warning in ext_warnings:
print(" * {}".format(ext_warning))
print("")

if not lookatme.prompt.yes("Continue anyways?"):
exit(1)


def contrib_first(fn):
"""A decorator that allows contrib modules to override default behavior
Expand Down
13 changes: 13 additions & 0 deletions lookatme/contrib/file_loader.py
Expand Up @@ -16,6 +16,19 @@
from lookatme.exceptions import IgnoredByContrib


def user_warnings():
"""Provide warnings to the user that loading this extension may cause
shell commands specified in the markdown to be run.
"""
return [
"Code-blocks with a language starting with 'file' may cause shell",
" commands from the source markdown to be run if the 'transform'",
" field is set",
"See https://lookatme.readthedocs.io/en/latest/builtin_extensions/file_loader.html",
" for more details",
]


class YamlRender:
loads = lambda data: yaml.safe_load(data)
dumps = lambda data: yaml.safe_dump(data)
Expand Down
12 changes: 12 additions & 0 deletions lookatme/contrib/terminal.py
Expand Up @@ -18,6 +18,18 @@
import lookatme.config


def user_warnings():
"""Provide warnings to the user that loading this extension may cause
shell commands specified in the markdown to be run.
"""
return [
"Code-blocks with a language starting with 'terminal' will cause shell",
" commands from the source markdown to be run",
"See https://lookatme.readthedocs.io/en/latest/builtin_extensions/terminal.html",
" for more details",
]


class YamlRender:
loads = lambda data: yaml.safe_load(data)
dumps = lambda data: yaml.safe_dump(data)
Expand Down

0 comments on commit 72fe36b

Please sign in to comment.