[Python-modules-commits] [humanfriendly] 14/17: Import humanfriendly_2.4.orig.tar.gz
Gaurav Juvekar
gauravjuvekar-guest at moszumanska.debian.org
Sun Mar 12 19:58:50 UTC 2017
This is an automated email from the git hooks/post-receive script.
gauravjuvekar-guest pushed a commit to branch master
in repository humanfriendly.
commit 7fe051f1be1e8e901a33e724a420d7689e4ce7b6
Author: Gaurav Juvekar <gauravjuvekar at gmail.com>
Date: Sun Mar 12 20:31:23 2017 +0100
Import humanfriendly_2.4.orig.tar.gz
---
PKG-INFO | 2 +-
humanfriendly.egg-info/PKG-INFO | 2 +-
humanfriendly/__init__.py | 42 ++++++++++++------------
humanfriendly/terminal.py | 73 +++++++++++++++++++++++++++++++----------
humanfriendly/tests.py | 31 ++++++++++++++++-
setup.py | 4 +--
6 files changed, 110 insertions(+), 44 deletions(-)
diff --git a/PKG-INFO b/PKG-INFO
index 97552fb..b4c1508 100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@ -1,6 +1,6 @@
Metadata-Version: 1.1
Name: humanfriendly
-Version: 2.3.2
+Version: 2.4
Summary: Human friendly output for text interfaces using Python
Home-page: https://humanfriendly.readthedocs.io
Author: Peter Odding
diff --git a/humanfriendly.egg-info/PKG-INFO b/humanfriendly.egg-info/PKG-INFO
index 97552fb..b4c1508 100644
--- a/humanfriendly.egg-info/PKG-INFO
+++ b/humanfriendly.egg-info/PKG-INFO
@@ -1,6 +1,6 @@
Metadata-Version: 1.1
Name: humanfriendly
-Version: 2.3.2
+Version: 2.4
Summary: Human friendly output for text interfaces using Python
Home-page: https://humanfriendly.readthedocs.io
Author: Peter Odding
diff --git a/humanfriendly/__init__.py b/humanfriendly/__init__.py
index f9cf8ed..50e1ae2 100644
--- a/humanfriendly/__init__.py
+++ b/humanfriendly/__init__.py
@@ -1,7 +1,7 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter at peterodding.com>
-# Last Change: January 17, 2017
+# Last Change: February 13, 2017
# URL: https://humanfriendly.readthedocs.io
"""The main module of the `humanfriendly` package."""
@@ -39,7 +39,7 @@ from humanfriendly.prompts import prompt_for_choice # NOQA
from humanfriendly.compat import is_string, monotonic
# Semi-standard module versioning.
-__version__ = '2.3.2'
+__version__ = '2.4'
# Spinners are redrawn at most this many seconds.
minimum_spinner_interval = 0.2
@@ -91,9 +91,9 @@ def coerce_boolean(value):
- The strings '0', 'no', 'false' and 'off' are coerced to :data:`False`.
- Other strings raise an exception.
- Other Python values are coerced using :py:func:`bool()`.
+ Other Python values are coerced using :func:`bool()`.
:returns: A proper boolean value.
- :raises: :py:exc:`exceptions.ValueError` when the value is a string but
+ :raises: :exc:`exceptions.ValueError` when the value is a string but
cannot be coerced with certainty.
"""
if is_string(value):
@@ -488,15 +488,15 @@ def parse_date(datestring):
>>> mktime(parse_date('2013-06-17 02:47:42') + (-1, -1, -1))
1371430062.0
- And here's how you convert it to a :py:class:`datetime.datetime` object:
+ And here's how you convert it to a :class:`datetime.datetime` object:
>>> from humanfriendly import parse_date
>>> from datetime import datetime
>>> datetime(*parse_date('2013-06-17 02:47:42'))
datetime.datetime(2013, 6, 17, 2, 47, 42)
- Here's an example that combines :py:func:`format_timespan()` and
- :py:func:`parse_date()` to calculate a human friendly timespan since a
+ Here's an example that combines :func:`format_timespan()` and
+ :func:`parse_date()` to calculate a human friendly timespan since a
given date:
>>> from humanfriendly import format_timespan, parse_date
@@ -559,9 +559,9 @@ def parse_path(pathname):
"""
Convert a human friendly pathname to an absolute pathname.
- Expands leading tildes using :py:func:`os.path.expanduser()` and
- environment variables using :py:func:`os.path.expandvars()` and makes the
- resulting pathname absolute using :py:func:`os.path.abspath()`.
+ Expands leading tildes using :func:`os.path.expanduser()` and
+ environment variables using :func:`os.path.expandvars()` and makes the
+ resulting pathname absolute using :func:`os.path.abspath()`.
:param pathname: A human friendly pathname (a string).
:returns: An absolute pathname (a string).
@@ -577,7 +577,7 @@ class Timer(object):
def __init__(self, start_time=None, resumable=False):
"""
- Remember the time when the :py:class:`Timer` was created.
+ Remember the time when the :class:`Timer` was created.
:param start_time: The start time (a float, defaults to the current time).
:param resumable: Create a resumable timer (defaults to :data:`False`).
@@ -727,8 +727,8 @@ class Spinner(object):
progress += random.random() * 5
If you want to provide user feedback during a long running operation but
- it's not practical to periodically call the :py:func:`~Spinner.step()`
- method consider using :py:class:`AutomaticSpinner` instead.
+ it's not practical to periodically call the :func:`~Spinner.step()`
+ method consider using :class:`AutomaticSpinner` instead.
As you may already have noticed in the examples above, :class:`Spinner`
objects can be used as context managers to automatically call
@@ -744,11 +744,11 @@ class Spinner(object):
:param label: The label for the spinner (a string, defaults to :data:`None`).
:param total: The expected number of steps (an integer).
:param stream: The output stream to show the spinner on (defaults to
- :py:data:`sys.stderr`).
+ :data:`sys.stderr`).
:param interactive: If this is :data:`False` then the spinner doesn't write
to the output stream at all. It defaults to the
return value of ``stream.isatty()``.
- :param timer: A :py:class:`Timer` object (optional). If this is given
+ :param timer: A :class:`Timer` object (optional). If this is given
the spinner will show the elapsed time according to the
timer.
:param hide_cursor: If :data:`True` (the default) the text cursor is hidden
@@ -857,20 +857,20 @@ class AutomaticSpinner(object):
"""
Show a spinner on the terminal that automatically starts animating.
- This class shows a spinner on the terminal (just like :py:class:`Spinner`
+ This class shows a spinner on the terminal (just like :class:`Spinner`
does) that automatically starts animating. This class should be used as a
- context manager using the :py:keyword:`with` statement. The animation
+ context manager using the :keyword:`with` statement. The animation
continues for as long as the context is active.
- :py:class:`AutomaticSpinner` provides an alternative to :py:class:`Spinner`
+ :class:`AutomaticSpinner` provides an alternative to :class:`Spinner`
for situations where it is not practical for the caller to periodically
- call :py:func:`~Spinner.step()` to advance the animation, e.g. because
+ call :func:`~Spinner.step()` to advance the animation, e.g. because
you're performing a blocking call and don't fancy implementing threading or
subprocess handling just to provide some user feedback.
- This works using the :py:mod:`multiprocessing` module by spawning a
+ This works using the :mod:`multiprocessing` module by spawning a
subprocess to render the spinner while the main process is busy doing
- something more useful. By using the :py:keyword:`with` statement you're
+ something more useful. By using the :keyword:`with` statement you're
guaranteed that the subprocess is properly terminated at the appropriate
time.
"""
diff --git a/humanfriendly/terminal.py b/humanfriendly/terminal.py
index 422bc0c..d97afd2 100644
--- a/humanfriendly/terminal.py
+++ b/humanfriendly/terminal.py
@@ -1,7 +1,7 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter at peterodding.com>
-# Last Change: October 9, 2016
+# Last Change: February 14, 2017
# URL: https://humanfriendly.readthedocs.io
"""
@@ -95,7 +95,7 @@ def message(*args, **kw):
"""
Show an informational message on the terminal.
- :param args: Any position arguments are passed on to :func:`~humanfriendly.text.format()`.
+ :param args: Any positional arguments are passed on to :func:`~humanfriendly.text.format()`.
:param kw: Any keyword arguments are passed on to :func:`~humanfriendly.text.format()`.
Renders the message using :func:`~humanfriendly.text.format()` and writes
@@ -108,7 +108,7 @@ def warning(*args, **kw):
"""
Show a warning message on the terminal.
- :param args: Any position arguments are passed on to :func:`~humanfriendly.text.format()`.
+ :param args: Any positional arguments are passed on to :func:`~humanfriendly.text.format()`.
:param kw: Any keyword arguments are passed on to :func:`~humanfriendly.text.format()`.
Renders the message using :func:`~humanfriendly.text.format()` and writes
@@ -157,7 +157,7 @@ def ansi_style(**kw):
enabled.
:returns: The ANSI escape sequences to enable the requested text styles or
an empty string if no styles were requested.
- :raises: :py:exc:`~exceptions.ValueError` when an invalid color name is given.
+ :raises: :exc:`~exceptions.ValueError` when an invalid color name is given.
"""
# Start with sequences that change text styles.
sequences = [str(ANSI_TEXT_STYLES[k]) for k, v in kw.items() if k in ANSI_TEXT_STYLES and v]
@@ -372,7 +372,7 @@ def find_terminal_size():
cached values!
Response: As a library I don't consider it the role of the
- :py:mod:`humanfriendly.terminal` module to install a process wide
+ :mod:`humanfriendly.terminal` module to install a process wide
signal handler ...
.. _Pre-emptive snarky comment: http://blogs.msdn.com/b/oldnewthing/archive/2008/01/30/7315957.aspx
@@ -460,25 +460,62 @@ def show_pager(formatted_text, encoding='UTF-8'):
:param encoding: The name of the text encoding used to encode the formatted
text if the formatted text is a Unicode string (a string).
+ When :func:`connected_to_terminal()` returns :data:`True` a pager is used
+ to show the text on the terminal, otherwise the text is printed directly
+ without invoking a pager.
+
The use of a pager helps to avoid the wall of text effect where the user
has to scroll up to see where the output began (not very user friendly).
- If :data:`sys.stdout` is not connected to a terminal (see
- :func:`connected_to_terminal()`) then the text is printed directly without
- invoking a pager.
-
- If the given text contains ANSI escape sequences the command ``less
- --RAW-CONTROL-CHARS`` is used, otherwise ``$PAGER`` is used (if ``$PAGER``
- isn't set the command ``less`` is used).
+ Refer to :func:`get_pager_command()` for details about the command line
+ that's used to invoke the pager.
"""
- if connected_to_terminal(sys.stdout):
- if ANSI_CSI in formatted_text:
- pager_command = ['less', '--RAW-CONTROL-CHARS']
- else:
- pager_command = [os.environ.get('PAGER', 'less')]
+ if connected_to_terminal():
+ command_line = get_pager_command(formatted_text)
+ pager = subprocess.Popen(command_line, stdin=subprocess.PIPE)
if is_unicode(formatted_text):
formatted_text = formatted_text.encode(encoding)
- pager = subprocess.Popen(pager_command, stdin=subprocess.PIPE)
pager.communicate(input=formatted_text)
else:
print(formatted_text)
+
+
+def get_pager_command(text=None):
+ """
+ Get the command to show a text on the terminal using a pager.
+
+ :param text: The text to print to the terminal (a string).
+ :returns: A list of strings with the pager command and arguments.
+
+ The use of a pager helps to avoid the wall of text effect where the user
+ has to scroll up to see where the output began (not very user friendly).
+
+ If the given text contains ANSI escape sequences the command ``less
+ --RAW-CONTROL-CHARS`` is used, otherwise the environment variable
+ ``$PAGER`` is used (if ``$PAGER`` isn't set less_ is used).
+
+ When the selected pager is less_, the following options are used to make
+ the experience more user friendly:
+
+ - ``--quit-if-one-screen`` causes less_ to automatically exit if the entire
+ text can be displayed on the first screen. This makes the use of a pager
+ transparent for smaller texts (because the operator doesn't have to quit
+ the pager).
+
+ - ``--no-init`` prevents less_ from clearing the screen when it exits. This
+ ensures that the operator gets a chance to review the text (for example a
+ usage message) after quitting the pager, while composing the next command.
+
+ .. _less: http://man7.org/linux/man-pages/man1/less.1.html
+ """
+ # Compose the pager command.
+ if text and ANSI_CSI in text:
+ command_line = ['less', '--RAW-CONTROL-CHARS']
+ else:
+ command_line = [os.environ.get('PAGER', 'less')]
+ # Pass some additional options to `less' (to make it more
+ # user friendly) without breaking support for other pagers.
+ if os.path.basename(command_line[0]) == 'less':
+ command_line.append('--no-init')
+ command_line.append('--quit-if-one-screen')
+ return command_line
diff --git a/humanfriendly/tests.py b/humanfriendly/tests.py
index 0a3878c..a0fcf66 100644
--- a/humanfriendly/tests.py
+++ b/humanfriendly/tests.py
@@ -4,7 +4,7 @@
# Tests for the `humanfriendly' package.
#
# Author: Peter Odding <peter.odding at paylogic.eu>
-# Last Change: January 17, 2017
+# Last Change: February 13, 2017
# URL: https://humanfriendly.readthedocs.io
"""Test suite for the `humanfriendly` package."""
@@ -51,6 +51,7 @@ from humanfriendly.terminal import (
clean_terminal_output,
connected_to_terminal,
find_terminal_size,
+ get_pager_command,
show_pager,
terminal_supports_colors,
)
@@ -688,6 +689,34 @@ class HumanFriendlyTestCase(unittest.TestCase):
# Clear the custom $PAGER value.
os.environ.pop('PAGER')
+ def test_get_pager_command(self):
+ """Test :func:`humanfriendly.terminal.get_pager_command()`."""
+ # Make sure --RAW-CONTROL-CHARS isn't used when it's not needed.
+ assert '--RAW-CONTROL-CHARS' not in get_pager_command("Usage message")
+ # Make sure --RAW-CONTROL-CHARS is used when it's needed.
+ assert '--RAW-CONTROL-CHARS' in get_pager_command(ansi_wrap("Usage message", bold=True))
+ # Make sure that less-specific options are only used when valid.
+ options_specific_to_less = ['--no-init', '--quit-if-one-screen']
+ for pager in 'cat', 'less':
+ original_pager = os.environ.get('PAGER', None)
+ try:
+ # Set $PAGER to `cat' or `less'.
+ os.environ['PAGER'] = pager
+ # Get the pager command line.
+ command_line = get_pager_command()
+ # Check for less-specific options.
+ if pager == 'less':
+ assert all(opt in command_line for opt in options_specific_to_less)
+ else:
+ assert not any(opt in command_line for opt in options_specific_to_less)
+ finally:
+ if original_pager is not None:
+ # Restore the original $PAGER value.
+ os.environ['PAGER'] = original_pager
+ else:
+ # Clear the custom $PAGER value.
+ os.environ.pop('PAGER')
+
def test_terminal_supports_colors(self):
"""Test :func:`humanfriendly.terminal.terminal_supports_colors()`."""
self.check_terminal_capabilities(terminal_supports_colors)
diff --git a/setup.py b/setup.py
index 6323018..c499e96 100755
--- a/setup.py
+++ b/setup.py
@@ -43,7 +43,7 @@ def get_version(*args):
def get_install_requires():
- """Add conditional dependencies for Python 2 (when creating source distributions)."""
+ """Get the conditional dependencies for source distributions."""
install_requires = []
if 'bdist_wheel' not in sys.argv:
if sys.version_info[:2] <= (2, 6) or sys.version_info[:2] == (3, 0):
@@ -54,7 +54,7 @@ def get_install_requires():
def get_extras_require():
- """Add conditional dependencies for Python 2 (when creating wheel distributions)."""
+ """Get the conditional dependencies for wheel distributions."""
extras_require = {}
if have_environment_marker_support():
# Conditional `importlib' dependency.
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/humanfriendly.git
More information about the Python-modules-commits
mailing list