Commit d8a14a4a authored by Grant Paton-Simpson's avatar Grant Paton-Simpson

Create temp markdown file as part of markdown output; misc

* Create temp markdown file as part of markdown output
* Improve documentation of using superhelp.this
* Add screenshot of markdown output
* Fix minor bug when items None after code execution
* Minor layout changes
* Bump version
parent 8390d9ef
Pipeline #578 failed with stages
# https://git.nzoss.org.nz/pyGrant/superhelp
version number: 0.9.16
version number: 0.9.17
author: Grant Paton-Simpson
## Overview
......@@ -14,10 +14,15 @@ the terminal and web browsers (perhaps as part of on-line tutorials).
## Quick Start
Click the button below to open a Binder Jupyter Notebook you can play around
in e.g. get advice on a line or snippet of Python
in e.g. get advice on a snippet or line of Python
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/git/https%3A%2F%2Fgit.nzoss.org.nz%2FpyGrant%2Fsuperhelp.git/master?filepath=notebooks%2FSuperhelpDemo.ipynb)
or put the following at the top of your Python script and run the script:
import superhelp
superhelp.this(__file__)
## Installation
Note - Python 3.6+ only. If you have an older version of Python use the Binder
......@@ -64,14 +69,18 @@ more often.
# Example Usage
## Screenshot from HTML
## Screenshot from HTML output
![Example HTML output](https://git.nzoss.org.nz/pyGrant/superhelp/-/raw/master/example_html_output_1.png)
## Screenshot from Terminal
## Screenshot from Terminal output
![Example Terminal output](https://git.nzoss.org.nz/pyGrant/superhelp/-/raw/master/example_terminal_output_1.png)
## Screenshot from Markdown output
![Example Markdown output](https://git.nzoss.org.nz/pyGrant/superhelp/-/raw/master/example_markdown_output_1.png)
## Using SuperHELP on the Notebook
Add new cell at end with content like:
......@@ -95,6 +104,21 @@ Put the following at the top of your script and then run the script (note - ther
import superhelp
superhelp.this(__file__)
If you don't want the default web output you can specify another displayer such as 'cli' (command line interface) or 'md' (markdown):
import superhelp
superhelp.this(__file__, displayer='md')
If you don't want the default 'Extra' level of messages you can specify a different message_level ('Brief' or 'Main') e.g.
import superhelp
superhelp.this(__file__, displayer='md', message_level='Brief')
or:
import superhelp
superhelp.this(__file__, message_level='Main')
### From the command line (terminal / console)
$ shelp -h ## get help on usage
......
......@@ -2,7 +2,7 @@ from setuptools import setup, find_packages # @UnresolvedImport
from codecs import open
from os import path
__version__ = '0.9.16'
__version__ = '0.9.17'
here = path.abspath(path.dirname(__file__))
......
......@@ -30,7 +30,6 @@ def dict_overview(block_dets, *, repeat=False):
for name, items in names_items:
if items is None:
brief_desc_bits.append(layout(f"""\
`{name}` is a dictionary. Unable to evaluate items.
"""))
else:
......@@ -42,7 +41,6 @@ def dict_overview(block_dets, *, repeat=False):
brief_desc = ''.join(brief_desc_bits)
if not repeat:
dict_def = layout("""\
Dictionaries map keys to values.
""")
workhorses = layout("""\
......@@ -51,25 +49,22 @@ def dict_overview(block_dets, *, repeat=False):
structures.
""")
keys_and_vals = layout("""\
Keys are unique but values can be repeated.
""")
dict_desc_bits = []
for i, (name, items) in enumerate(names_items, 0):
if i == 0:
first_name = name
first_name = None
for name, items in names_items:
if not items:
dict_desc_bits.append(layout(f"""\
`{name}` is a dictionary. Unable to evaluate items.
"""))
else:
if not first_name:
first_name = name
empty_dict = (len(items) == 0)
if empty_dict:
dict_desc_bits.append(layout(f"""\
`{name}` is an empty dictionary.
"""))
else:
plural = '' if len(items) == 1 else 's'
......@@ -83,6 +78,8 @@ def dict_overview(block_dets, *, repeat=False):
{list(items.values())}. We can get the values using the
`.values()` method e.g. `{name}`.`values()`.
"""))
if first_name is None:
first_name = 'demo_dict'
main_dict_desc = ''.join(dict_desc_bits)
general = (
layout(f"""
......@@ -99,8 +96,7 @@ def dict_overview(block_dets, *, repeat=False):
print(f"key {{k}} maps to value {{v}}")
""", is_code=True)
+
layout(f"""
layout("""
Keys are unique but values can be repeated. For example:
""")
+
......
......@@ -30,10 +30,6 @@ def get_type_for_example(list_items):
return type4example
def _get_detailed_list_comment(first_name, first_items):
"""
:param list first_items: note - may be None if a list is defined in a
function
"""
type4example = get_type_for_example(first_items)
try:
example_items = conf.EXAMPLES_OF_TYPES[type4example]
......@@ -168,6 +164,9 @@ def list_overview(block_dets, *, repeat=False):
`{name}` is a list with {utils.int2nice(len(items))} items.
""")
if not first_name:
first_name = 'demo_list'
first_items = ['apple', 'banana', 'cherry', ]
if not repeat:
brief_overview = layout("""\
......
......@@ -30,10 +30,31 @@ else:
## When testing user-supplied snippets watch out for the BOM MS inserts via Notepad. AST chokes on it.
## All snippets here should be raw strings (see https://stackoverflow.com/questions/53636723/python-parsing-code-with-new-line-character-in-them-using-ast)
TEST_SNIPPET = r"""
p1 = print
p2 = 'print'
print = 'sausage'
p3 = print
from random import choice
import asyncio
async def run_job(num):
await asyncio.sleep(choice([0.1, 3, 1, 10, 0.5]))
return f"I slept for {num:,} seconds!"
async def run_jobs():
jobs = []
for num in range(1, 11):
job = run_job(num) ## not await because we don't want the result but the future itself ready to be submitted
jobs.append(job)
done_jobs, _pending = await asyncio.wait(jobs,
return_when=asyncio.FIRST_COMPLETED)
results = [done_job.result() for done_job in done_jobs]
return results
loop = asyncio.get_event_loop()
try:
results = loop.run_until_complete(run_jobs())
for result in results:
print(result)
finally:
loop.close()
"""
PY3_6 = '3.6'
......
import logging
from textwrap import dedent
from ..utils import get_line_numbered_snippet, layout_comment as layout
from ..utils import get_line_numbered_snippet, layout_comment as layout, \
make_open_tmp_file
"""
Note - plain MDV - works in some consoles where terminal output fails.
Lots in common with cli displayer but risks of DRYing probably outweigh benefits
at this stage.
Makes temp MD file and displays its content.
"""
from .. import conf
......@@ -96,4 +99,11 @@ def display(snippet, messages_dets, *,
message = get_message(message_dets, message_level)
text.append(message)
content = '\n'.join(text)
tmp_fh, fpath = make_open_tmp_file('superhelp_output.md', mode='w')
tmp_fh.write(content)
tmp_fh.close()
print(content)
print(f"""\
{'-' * 10} Content above this line saved as temp file {'-' * 10}
Temp file: {fpath}
""")
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment