Menu
▾
▴
[Docutils-develop] Print info and prompt when waiting for input from terminal (patch).
|
From: Guenter M. <mi...@us...> - 2022-02-11 00:25:54
|
Dear Docutils developers,
please find attached a patch suggestion improving the front-end tool user
experience.
Feedback welcome,
Günter
Subject: [PATCH] core.Publisher.publish(): Prompt when waiting for input from a terminal.
When front-end tools are used without arguments, Docutils reads
from stdin. After calling `rst2html.py`, say, from a terminal
there was no response until the user guessed right and
pressed Ctrl-D (or Ctrl-Z on Windows) or aborted with Ctrl-C.
With the addition, Doctils tells the user what it expects and where to
get more help.
---
docutils/HISTORY.txt | 5 +++++
docutils/docs/dev/todo.txt | 10 ++++++++++
docutils/docutils/core.py | 40 +++++++++++++++++++++++++---------------
docutils/docutils/io.py | 12 ++++++++++++
docutils/docutils/parsers/rst/__init__.py | 2 +-
docutils/docutils/writers/html5_polyglot/__init__.py | 2 +-
docutils/docutils/writers/pseudoxml.py | 2 +-
docutils/docutils/writers/xetex/__init__.py | 2 +-
8 files changed, 56 insertions(+), 19 deletions(-)
diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 1f3879d..7e85d33 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -32,4 +32,9 @@ Changes Since 0.18.1
__ https://www.python.org/dev/peps/pep-0621/#entry-points
+* docutils/core.py:
+
+ Publisher.publish(): Print info and prompt when waiting for input from
+ a terminal cf. https://clig.dev/#interactivity.
+
* docutils/parsers/__init__.py
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index 5f175d2..eda93a4 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -2867,4 +2867,14 @@ Front-End Tools
line option then.
+* Implement the following suggestions from clig.dev?
+
+ Display output on success, but keep it brief.
+ provide a --quiet option to suppress all non-essential output.
+
+ Consider chaining several args as input and use --output
+ (or redirection) for output.
+
+ -- https://clig.dev/#help
+
.. _partial parsing:
https://docs.python.org/3/library/argparse.html#partial-parsing
diff --git a/docutils/docutils/core.py b/docutils/docutils/core.py
index 6301cf4..b7694c4 100644
--- a/docutils/docutils/core.py
+++ b/docutils/docutils/core.py
@@ -15,4 +15,5 @@ custom component objects first, and pass *them* to
__docformat__ = 'reStructuredText'
+import os
import sys
import pprint
@@ -77,4 +78,5 @@ class Publisher:
self._stderr = io.ErrorOutput()
+
def set_reader(self, reader_name, parser, parser_name):
"""Set `self.reader` by name."""
@@ -203,4 +205,5 @@ class Publisher:
**(settings_overrides or {}))
self.set_io()
+ self.prompt()
self.document = self.reader.read(self.source, self.parser,
self.settings)
@@ -252,4 +255,26 @@ class Publisher:
'raw_unicode_escape'), file=self._stderr)
+ def prompt(self):
+ """Print info and prompt when waiting for input from a terminal."""
+ try:
+ if not (self.source.isatty() and self._stderr.isatty()):
+ return
+ except AttributeError:
+ return
+ eot_key = 'Ctrl+Z' if os.name == 'nt' else 'Ctrl+D on an empty line'
+ in_format = 'plaintext'
+ out_format = 'useful formats'
+ try:
+ in_format = self.parser.supported[0]
+ out_format = self.writer.supported[0]
+ except (AttributeError, IndexError):
+ pass
+ print(f'Docutils {__version__} '
+ f'converting {in_format} into {out_format}.\n'
+ 'See <https://docutils.sourceforge.io> '
+ f'or use option "--help" for more info.\n'
+ f'.. Type/paste source text (finish with {eot_key}):',
+ file=self._stderr)
+
def report_Exception(self, error):
if isinstance(error, utils.SystemMessage):
@@ -317,19 +342,4 @@ default_description = ('Reads from <source> (default is stdin) and writes to '
'the full reference.')
-# TODO:
-# require source ('-' for stdin)?
-#
-# print usage if there is no arg
-# (always or if sys.stdout.isatty() ?)
-# Alternatively, print a log message to stderr.
-#
-# Display output on success, but keep it brief.
-# provide a -q option to suppress all non-essential output.
-#
-# Consider chaining several args as input
-# and use --output (or redirection) for output
-# argparser.add_argument('source', nargs='+')
-#
-# -- https://clig.dev/#help
def publish_cmdline(reader=None, reader_name='standalone',
diff --git a/docutils/docutils/io.py b/docutils/docutils/io.py
index 7f65df6..c73c550 100644
--- a/docutils/docutils/io.py
+++ b/docutils/docutils/io.py
@@ -175,4 +175,10 @@ class Input(TransformSpec):
return None
+ def isatty(self):
+ try:
+ return self.source.isatty()
+ except AttributeError:
+ return False
+
class Output(TransformSpec):
@@ -303,4 +309,10 @@ class ErrorOutput:
pass
+ def isatty(self):
+ try:
+ return self.destination.isatty()
+ except AttributeError:
+ return False
+
class FileInput(Input):
diff --git a/docutils/docutils/parsers/rst/__init__.py b/docutils/docutils/parsers/rst/__init__.py
index 7831752..4d2a294 100644
--- a/docutils/docutils/parsers/rst/__init__.py
+++ b/docutils/docutils/parsers/rst/__init__.py
@@ -82,5 +82,5 @@ class Parser(docutils.parsers.Parser):
"""The reStructuredText parser."""
- supported = ('restructuredtext', 'rst', 'rest', 'restx', 'rtxt', 'rstx')
+ supported = ('rst', 'rest', 'restructuredtext', 'restx', 'rtxt', 'rstx')
"""Aliases this parser supports."""
diff --git a/docutils/docutils/writers/html5_polyglot/__init__.py b/docutils/docutils/writers/html5_polyglot/__init__.py
index 2771a84..fca141e 100644
--- a/docutils/docutils/writers/html5_polyglot/__init__.py
+++ b/docutils/docutils/writers/html5_polyglot/__init__.py
@@ -37,5 +37,5 @@ from docutils.writers import _html_base
class Writer(writers._html_base.Writer):
- supported = ('html', 'html5', 'xhtml')
+ supported = ('html5', 'xhtml', 'html')
"""Formats this writer supports."""
diff --git a/docutils/docutils/writers/pseudoxml.py b/docutils/docutils/writers/pseudoxml.py
index b10a2d0..6f4a507 100644
--- a/docutils/docutils/writers/pseudoxml.py
+++ b/docutils/docutils/writers/pseudoxml.py
@@ -15,5 +15,5 @@ from docutils import writers, frontend
class Writer(writers.Writer):
- supported = ('pprint', 'pformat', 'pseudoxml')
+ supported = ('pseudoxml', 'pprint', 'pformat')
"""Formats this writer supports."""
diff --git a/docutils/docutils/writers/xetex/__init__.py b/docutils/docutils/writers/xetex/__init__.py
index 4dadbc7..f785e07 100644
--- a/docutils/docutils/writers/xetex/__init__.py
+++ b/docutils/docutils/writers/xetex/__init__.py
@@ -32,5 +32,5 @@ class Writer(latex2e.Writer):
"""A writer for Unicode-aware LaTeX variants (XeTeX, LuaTeX)"""
- supported = ('lxtex', 'xetex', 'xelatex', 'luatex', 'lualatex')
+ supported = ('latex', 'tex', 'xetex', 'xelatex', 'luatex', 'lualatex')
"""Formats this writer supports."""
--
libgit2 1.1.0
|
