Mercurial > repos > shellac > sam_consensus_v3
view env/lib/python3.9/site-packages/humanfriendly/tests.py @ 0:4f3585e2f14b draft default tip
"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"
| author | shellac |
|---|---|
| date | Mon, 22 Mar 2021 18:12:50 +0000 |
| parents | |
| children |
line wrap: on
line source
#!/usr/bin/env python # vim: fileencoding=utf-8 : # Tests for the `humanfriendly' package. # # Author: Peter Odding <peter.odding@paylogic.eu> # Last Change: December 1, 2020 # URL: https://humanfriendly.readthedocs.io """Test suite for the `humanfriendly` package.""" # Standard library modules. import datetime import math import os import random import re import subprocess import sys import time import types import unittest import warnings # Modules included in our package. from humanfriendly import ( InvalidDate, InvalidLength, InvalidSize, InvalidTimespan, Timer, coerce_boolean, coerce_pattern, format_length, format_number, format_path, format_size, format_timespan, parse_date, parse_length, parse_path, parse_size, parse_timespan, prompts, round_number, ) from humanfriendly.case import CaseInsensitiveDict, CaseInsensitiveKey from humanfriendly.cli import main from humanfriendly.compat import StringIO from humanfriendly.decorators import cached from humanfriendly.deprecation import DeprecationProxy, define_aliases, deprecated_args, get_aliases from humanfriendly.prompts import ( TooManyInvalidReplies, prompt_for_confirmation, prompt_for_choice, prompt_for_input, ) from humanfriendly.sphinx import ( deprecation_note_callback, man_role, pypi_role, setup, special_methods_callback, usage_message_callback, ) from humanfriendly.tables import ( format_pretty_table, format_robust_table, format_rst_table, format_smart_table, ) from humanfriendly.terminal import ( ANSI_CSI, ANSI_ERASE_LINE, ANSI_HIDE_CURSOR, ANSI_RESET, ANSI_SGR, ANSI_SHOW_CURSOR, ansi_strip, ansi_style, ansi_width, ansi_wrap, clean_terminal_output, connected_to_terminal, find_terminal_size, get_pager_command, message, output, show_pager, terminal_supports_colors, warning, ) from humanfriendly.terminal.html import html_to_ansi from humanfriendly.terminal.spinners import AutomaticSpinner, Spinner from humanfriendly.testing import ( CallableTimedOut, CaptureOutput, MockedProgram, PatchedAttribute, PatchedItem, TemporaryDirectory, TestCase, retry, run_cli, skip_on_raise, touch, ) from humanfriendly.text import ( compact, compact_empty_lines, concatenate, dedent, generate_slug, pluralize, random_string, trim_empty_lines, ) from humanfriendly.usage import ( find_meta_variables, format_usage, parse_usage, render_usage, ) # Test dependencies. from mock import MagicMock class HumanFriendlyTestCase(TestCase): """Container for the `humanfriendly` test suite.""" def test_case_insensitive_dict(self): """Test the CaseInsensitiveDict class.""" # Test support for the dict(iterable) signature. assert len(CaseInsensitiveDict([('key', True), ('KEY', False)])) == 1 # Test support for the dict(iterable, **kw) signature. assert len(CaseInsensitiveDict([('one', True), ('ONE', False)], one=False, two=True)) == 2 # Test support for the dict(mapping) signature. assert len(CaseInsensitiveDict(dict(key=True, KEY=False))) == 1 # Test support for the dict(mapping, **kw) signature. assert len(CaseInsensitiveDict(dict(one=True, ONE=False), one=False, two=True)) == 2 # Test support for the dict(**kw) signature. assert len(CaseInsensitiveDict(one=True, ONE=False, two=True)) == 2 # Test support for dict.fromkeys(). obj = CaseInsensitiveDict.fromkeys(["One", "one", "ONE", "Two", "two", "TWO"]) assert len(obj) == 2 # Test support for dict.get(). obj = CaseInsensitiveDict(existing_key=42) assert obj.get('Existing_Key') == 42 # Test support for dict.pop(). obj = CaseInsensitiveDict(existing_key=42) assert obj.pop('Existing_Key') == 42 assert len(obj) == 0 # Test support for dict.setdefault(). obj = CaseInsensitiveDict(existing_key=42) assert obj.setdefault('Existing_Key') == 42 obj.setdefault('other_key', 11) assert obj['Other_Key'] == 11 # Test support for dict.__contains__(). obj = CaseInsensitiveDict(existing_key=42) assert 'Existing_Key' in obj # Test support for dict.__delitem__(). obj = CaseInsensitiveDict(existing_key=42) del obj['Existing_Key'] assert len(obj) == 0 # Test support for dict.__getitem__(). obj = CaseInsensitiveDict(existing_key=42) assert obj['Existing_Key'] == 42 # Test support for dict.__setitem__(). obj = CaseInsensitiveDict(existing_key=42) obj['Existing_Key'] = 11 assert obj['existing_key'] == 11 def test_case_insensitive_key(self): """Test the CaseInsensitiveKey class.""" # Test the __eq__() special method. polite = CaseInsensitiveKey("Please don't shout") rude = CaseInsensitiveKey("PLEASE DON'T SHOUT") assert polite == rude # Test the __hash__() special method. mapping = {} mapping[polite] = 1 mapping[rude] = 2 assert len(mapping) == 1 def test_capture_output(self): """Test the CaptureOutput class.""" with CaptureOutput() as capturer: sys.stdout.write("Something for stdout.\n") sys.stderr.write("And for stderr.\n") assert capturer.stdout.get_lines() == ["Something for stdout."] assert capturer.stderr.get_lines() == ["And for stderr."] def test_skip_on_raise(self): """Test the skip_on_raise() decorator.""" def test_fn(): raise NotImplementedError() decorator_fn = skip_on_raise(NotImplementedError) decorated_fn = decorator_fn(test_fn) self.assertRaises(NotImplementedError, test_fn) self.assertRaises(unittest.SkipTest, decorated_fn) def test_retry_raise(self): """Test :func:`~humanfriendly.testing.retry()` based on assertion errors.""" # Define a helper function that will raise an assertion error on the # first call and return a string on the second call. def success_helper(): if not hasattr(success_helper, 'was_called'): setattr(success_helper, 'was_called', True) assert False else: return 'yes' assert retry(success_helper) == 'yes' # Define a helper function that always raises an assertion error. def failure_helper(): assert False with self.assertRaises(AssertionError): retry(failure_helper, timeout=1) def test_retry_return(self): """Test :func:`~humanfriendly.testing.retry()` based on return values.""" # Define a helper function that will return False on the first call and # return a number on the second call. def success_helper(): if not hasattr(success_helper, 'was_called'): # On the first call we return False. setattr(success_helper, 'was_called', True) return False else: # On the second call we return a number. return 42 assert retry(success_helper) == 42 with self.assertRaises(CallableTimedOut): retry(lambda: False, timeout=1) def test_mocked_program(self): """Test :class:`humanfriendly.testing.MockedProgram`.""" name = random_string() script = dedent(''' # This goes to stdout. tr a-z A-Z # This goes to stderr. echo Fake warning >&2 ''') with MockedProgram(name=name, returncode=42, script=script) as directory: assert os.path.isdir(directory) assert os.path.isfile(os.path.join(directory, name)) program = subprocess.Popen(name, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE) stdout, stderr = program.communicate(input=b'hello world\n') assert program.returncode == 42 assert stdout == b'HELLO WORLD\n' assert stderr == b'Fake warning\n' def test_temporary_directory(self): """Test :class:`humanfriendly.testing.TemporaryDirectory`.""" with TemporaryDirectory() as directory: assert os.path.isdir(directory) temporary_file = os.path.join(directory, 'some-file') with open(temporary_file, 'w') as handle: handle.write("Hello world!") assert not os.path.exists(temporary_file) assert not os.path.exists(directory) def test_touch(self): """Test :func:`humanfriendly.testing.touch()`.""" with TemporaryDirectory() as directory: # Create a file in the temporary directory. filename = os.path.join(directory, random_string()) assert not os.path.isfile(filename) touch(filename) assert os.path.isfile(filename) # Create a file in a subdirectory. filename = os.path.join(directory, random_string(), random_string()) assert not os.path.isfile(filename) touch(filename) assert os.path.isfile(filename) def test_patch_attribute(self): """Test :class:`humanfriendly.testing.PatchedAttribute`.""" class Subject(object): my_attribute = 42 instance = Subject() assert instance.my_attribute == 42 with PatchedAttribute(instance, 'my_attribute', 13) as return_value: assert return_value is instance assert instance.my_attribute == 13 assert instance.my_attribute == 42 def test_patch_item(self): """Test :class:`humanfriendly.testing.PatchedItem`.""" instance = dict(my_item=True) assert instance['my_item'] is True with PatchedItem(instance, 'my_item', False) as return_value: assert return_value is instance assert instance['my_item'] is False assert instance['my_item'] is True def test_run_cli_intercepts_exit(self): """Test that run_cli() intercepts SystemExit.""" returncode, output = run_cli(lambda: sys.exit(42)) self.assertEqual(returncode, 42) def test_run_cli_intercepts_error(self): """Test that run_cli() intercepts exceptions.""" returncode, output = run_cli(self.run_cli_raise_other) self.assertEqual(returncode, 1) def run_cli_raise_other(self): """run_cli() sample that raises an exception.""" raise ValueError() def test_run_cli_intercepts_output(self): """Test that run_cli() intercepts output.""" expected_output = random_string() + "\n" returncode, output = run_cli(lambda: sys.stdout.write(expected_output)) self.assertEqual(returncode, 0) self.assertEqual(output, expected_output) def test_caching_decorator(self): """Test the caching decorator.""" # Confirm that the caching decorator works. a = cached(lambda: random.random()) b = cached(lambda: random.random()) assert a() == a() assert b() == b() # Confirm that functions have their own cache. assert a() != b() def test_compact(self): """Test :func:`humanfriendly.text.compact()`.""" assert compact(' a \n\n b ') == 'a b' assert compact(''' %s template notation ''', 'Simple') == 'Simple template notation' assert compact(''' More {type} template notation ''', type='readable') == 'More readable template notation' def test_compact_empty_lines(self): """Test :func:`humanfriendly.text.compact_empty_lines()`.""" # Simple strings pass through untouched. assert compact_empty_lines('foo') == 'foo' # Horizontal whitespace remains untouched. assert compact_empty_lines('\tfoo') == '\tfoo' # Line breaks should be preserved. assert compact_empty_lines('foo\nbar') == 'foo\nbar' # Vertical whitespace should be preserved. assert compact_empty_lines('foo\n\nbar') == 'foo\n\nbar' # Vertical whitespace should be compressed. assert compact_empty_lines('foo\n\n\nbar') == 'foo\n\nbar' assert compact_empty_lines('foo\n\n\n\nbar') == 'foo\n\nbar' assert compact_empty_lines('foo\n\n\n\n\nbar') == 'foo\n\nbar' def test_dedent(self): """Test :func:`humanfriendly.text.dedent()`.""" assert dedent('\n line 1\n line 2\n\n') == 'line 1\n line 2\n' assert dedent(''' Dedented, %s text ''', 'interpolated') == 'Dedented, interpolated text\n' assert dedent(''' Dedented, {op} text ''', op='formatted') == 'Dedented, formatted text\n' def test_pluralization(self): """Test :func:`humanfriendly.text.pluralize()`.""" assert pluralize(1, 'word') == '1 word' assert pluralize(2, 'word') == '2 words' assert pluralize(1, 'box', 'boxes') == '1 box' assert pluralize(2, 'box', 'boxes') == '2 boxes' def test_generate_slug(self): """Test :func:`humanfriendly.text.generate_slug()`.""" # Test the basic functionality. self.assertEqual('some-random-text', generate_slug('Some Random Text!')) # Test that previous output doesn't change. self.assertEqual('some-random-text', generate_slug('some-random-text')) # Test that inputs which can't be converted to a slug raise an exception. with self.assertRaises(ValueError): generate_slug(' ') with self.assertRaises(ValueError): generate_slug('-') def test_boolean_coercion(self): """Test :func:`humanfriendly.coerce_boolean()`.""" for value in [True, 'TRUE', 'True', 'true', 'on', 'yes', '1']: self.assertEqual(True, coerce_boolean(value)) for value in [False, 'FALSE', 'False', 'false', 'off', 'no', '0']: self.assertEqual(False, coerce_boolean(value)) with self.assertRaises(ValueError): coerce_boolean('not a boolean') def test_pattern_coercion(self): """Test :func:`humanfriendly.coerce_pattern()`.""" empty_pattern = re.compile('') # Make sure strings are converted to compiled regular expressions. assert isinstance(coerce_pattern('foobar'), type(empty_pattern)) # Make sure compiled regular expressions pass through untouched. assert empty_pattern is coerce_pattern(empty_pattern) # Make sure flags are respected. pattern = coerce_pattern('foobar', re.IGNORECASE) assert pattern.match('FOOBAR') # Make sure invalid values raise the expected exception. with self.assertRaises(ValueError): coerce_pattern([]) def test_format_timespan(self): """Test :func:`humanfriendly.format_timespan()`.""" minute = 60 hour = minute * 60 day = hour * 24 week = day * 7 year = week * 52 assert '1 nanosecond' == format_timespan(0.000000001, detailed=True) assert '500 nanoseconds' == format_timespan(0.0000005, detailed=True) assert '1 microsecond' == format_timespan(0.000001, detailed=True) assert '500 microseconds' == format_timespan(0.0005, detailed=True) assert '1 millisecond' == format_timespan(0.001, detailed=True) assert '500 milliseconds' == format_timespan(0.5, detailed=True) assert '0.5 seconds' == format_timespan(0.5, detailed=False) assert '0 seconds' == format_timespan(0) assert '0.54 seconds' == format_timespan(0.54321) assert '1 second' == format_timespan(1) assert '3.14 seconds' == format_timespan(math.pi) assert '1 minute' == format_timespan(minute) assert '1 minute and 20 seconds' == format_timespan(80) assert '2 minutes' == format_timespan(minute * 2) assert '1 hour' == format_timespan(hour) assert '2 hours' == format_timespan(hour * 2) assert '1 day' == format_timespan(day) assert '2 days' == format_timespan(day * 2) assert '1 week' == format_timespan(week) assert '2 weeks' == format_timespan(week * 2) assert '1 year' == format_timespan(year) assert '2 years' == format_timespan(year * 2) assert '6 years, 5 weeks, 4 days, 3 hours, 2 minutes and 500 milliseconds' == \ format_timespan(year * 6 + week * 5 + day * 4 + hour * 3 + minute * 2 + 0.5, detailed=True) assert '1 year, 2 weeks and 3 days' == \ format_timespan(year + week * 2 + day * 3 + hour * 12) # Make sure milliseconds are never shown separately when detailed=False. # https://github.com/xolox/python-humanfriendly/issues/10 assert '1 minute, 1 second and 100 milliseconds' == format_timespan(61.10, detailed=True) assert '1 minute and 1.1 seconds' == format_timespan(61.10, detailed=False) # Test for loss of precision as reported in issue 11: # https://github.com/xolox/python-humanfriendly/issues/11 assert '1 minute and 0.3 seconds' == format_timespan(60.300) assert '5 minutes and 0.3 seconds' == format_timespan(300.300) assert '1 second and 15 milliseconds' == format_timespan(1.015, detailed=True) assert '10 seconds and 15 milliseconds' == format_timespan(10.015, detailed=True) assert '1 microsecond and 50 nanoseconds' == format_timespan(0.00000105, detailed=True) # Test the datetime.timedelta support: # https://github.com/xolox/python-humanfriendly/issues/27 now = datetime.datetime.now() then = now - datetime.timedelta(hours=23) assert '23 hours' == format_timespan(now - then) def test_parse_timespan(self): """Test :func:`humanfriendly.parse_timespan()`.""" self.assertEqual(0, parse_timespan('0')) self.assertEqual(0, parse_timespan('0s')) self.assertEqual(0.000000001, parse_timespan('1ns')) self.assertEqual(0.000000051, parse_timespan('51ns')) self.assertEqual(0.000001, parse_timespan('1us')) self.assertEqual(0.000052, parse_timespan('52us')) self.assertEqual(0.001, parse_timespan('1ms')) self.assertEqual(0.001, parse_timespan('1 millisecond')) self.assertEqual(0.5, parse_timespan('500 milliseconds')) self.assertEqual(0.5, parse_timespan('0.5 seconds')) self.assertEqual(5, parse_timespan('5s')) self.assertEqual(5, parse_timespan('5 seconds')) self.assertEqual(60 * 2, parse_timespan('2m')) self.assertEqual(60 * 2, parse_timespan('2 minutes')) self.assertEqual(60 * 3, parse_timespan('3 min')) self.assertEqual(60 * 3, parse_timespan('3 mins')) self.assertEqual(60 * 60 * 3, parse_timespan('3 h')) self.assertEqual(60 * 60 * 3, parse_timespan('3 hours')) self.assertEqual(60 * 60 * 24 * 4, parse_timespan('4d')) self.assertEqual(60 * 60 * 24 * 4, parse_timespan('4 days')) self.assertEqual(60 * 60 * 24 * 7 * 5, parse_timespan('5 w')) self.assertEqual(60 * 60 * 24 * 7 * 5, parse_timespan('5 weeks')) with self.assertRaises(InvalidTimespan): parse_timespan('1z') def test_parse_date(self): """Test :func:`humanfriendly.parse_date()`.""" self.assertEqual((2013, 6, 17, 0, 0, 0), parse_date('2013-06-17')) self.assertEqual((2013, 6, 17, 2, 47, 42), parse_date('2013-06-17 02:47:42')) self.assertEqual((2016, 11, 30, 0, 47, 17), parse_date(u'2016-11-30 00:47:17')) with self.assertRaises(InvalidDate): parse_date('2013-06-XY') def test_format_size(self): """Test :func:`humanfriendly.format_size()`.""" self.assertEqual('0 bytes', format_size(0)) self.assertEqual('1 byte', format_size(1)) self.assertEqual('42 bytes', format_size(42)) self.assertEqual('1 KB', format_size(1000 ** 1)) self.assertEqual('1 MB', format_size(1000 ** 2)) self.assertEqual('1 GB', format_size(1000 ** 3)) self.assertEqual('1 TB', format_size(1000 ** 4)) self.assertEqual('1 PB', format_size(1000 ** 5)) self.assertEqual('1 EB', format_size(1000 ** 6)) self.assertEqual('1 ZB', format_size(1000 ** 7)) self.assertEqual('1 YB', format_size(1000 ** 8)) self.assertEqual('1 KiB', format_size(1024 ** 1, binary=True)) self.assertEqual('1 MiB', format_size(1024 ** 2, binary=True)) self.assertEqual('1 GiB', format_size(1024 ** 3, binary=True)) self.assertEqual('1 TiB', format_size(1024 ** 4, binary=True)) self.assertEqual('1 PiB', format_size(1024 ** 5, binary=True)) self.assertEqual('1 EiB', format_size(1024 ** 6, binary=True)) self.assertEqual('1 ZiB', format_size(1024 ** 7, binary=True)) self.assertEqual('1 YiB', format_size(1024 ** 8, binary=True)) self.assertEqual('45 KB', format_size(1000 * 45)) self.assertEqual('2.9 TB', format_size(1000 ** 4 * 2.9)) def test_parse_size(self): """Test :func:`humanfriendly.parse_size()`.""" self.assertEqual(0, parse_size('0B')) self.assertEqual(42, parse_size('42')) self.assertEqual(42, parse_size('42B')) self.assertEqual(1000, parse_size('1k')) self.assertEqual(1024, parse_size('1k', binary=True)) self.assertEqual(1000, parse_size('1 KB')) self.assertEqual(1000, parse_size('1 kilobyte')) self.assertEqual(1024, parse_size('1 kilobyte', binary=True)) self.assertEqual(1000 ** 2 * 69, parse_size('69 MB')) self.assertEqual(1000 ** 3, parse_size('1 GB')) self.assertEqual(1000 ** 4, parse_size('1 TB')) self.assertEqual(1000 ** 5, parse_size('1 PB')) self.assertEqual(1000 ** 6, parse_size('1 EB')) self.assertEqual(1000 ** 7, parse_size('1 ZB')) self.assertEqual(1000 ** 8, parse_size('1 YB')) self.assertEqual(1000 ** 3 * 1.5, parse_size('1.5 GB')) self.assertEqual(1024 ** 8 * 1.5, parse_size('1.5 YiB')) with self.assertRaises(InvalidSize): parse_size('1q') with self.assertRaises(InvalidSize): parse_size('a') def test_format_length(self): """Test :func:`humanfriendly.format_length()`.""" self.assertEqual('0 metres', format_length(0)) self.assertEqual('1 metre', format_length(1)) self.assertEqual('42 metres', format_length(42)) self.assertEqual('1 km', format_length(1 * 1000)) self.assertEqual('15.3 cm', format_length(0.153)) self.assertEqual('1 cm', format_length(1e-02)) self.assertEqual('1 mm', format_length(1e-03)) self.assertEqual('1 nm', format_length(1e-09)) def test_parse_length(self): """Test :func:`humanfriendly.parse_length()`.""" self.assertEqual(0, parse_length('0m')) self.assertEqual(42, parse_length('42')) self.assertEqual(1.5, parse_length('1.5')) self.assertEqual(42, parse_length('42m')) self.assertEqual(1000, parse_length('1km')) self.assertEqual(0.153, parse_length('15.3 cm')) self.assertEqual(1e-02, parse_length('1cm')) self.assertEqual(1e-03, parse_length('1mm')) self.assertEqual(1e-09, parse_length('1nm')) with self.assertRaises(InvalidLength): parse_length('1z') with self.assertRaises(InvalidLength): parse_length('a') def test_format_number(self): """Test :func:`humanfriendly.format_number()`.""" self.assertEqual('1', format_number(1)) self.assertEqual('1.5', format_number(1.5)) self.assertEqual('1.56', format_number(1.56789)) self.assertEqual('1.567', format_number(1.56789, 3)) self.assertEqual('1,000', format_number(1000)) self.assertEqual('1,000', format_number(1000.12, 0)) self.assertEqual('1,000,000', format_number(1000000)) self.assertEqual('1,000,000.42', format_number(1000000.42)) # Regression test for https://github.com/xolox/python-humanfriendly/issues/40. self.assertEqual('-285.67', format_number(-285.67)) def test_round_number(self): """Test :func:`humanfriendly.round_number()`.""" self.assertEqual('1', round_number(1)) self.assertEqual('1', round_number(1.0)) self.assertEqual('1.00', round_number(1, keep_width=True)) self.assertEqual('3.14', round_number(3.141592653589793)) def test_format_path(self): """Test :func:`humanfriendly.format_path()`.""" friendly_path = os.path.join('~', '.vimrc') absolute_path = os.path.join(os.environ['HOME'], '.vimrc') self.assertEqual(friendly_path, format_path(absolute_path)) def test_parse_path(self): """Test :func:`humanfriendly.parse_path()`.""" friendly_path = os.path.join('~', '.vimrc') absolute_path = os.path.join(os.environ['HOME'], '.vimrc') self.assertEqual(absolute_path, parse_path(friendly_path)) def test_pretty_tables(self): """Test :func:`humanfriendly.tables.format_pretty_table()`.""" # The simplest case possible :-). data = [['Just one column']] assert format_pretty_table(data) == dedent(""" ------------------- | Just one column | ------------------- """).strip() # A bit more complex: two rows, three columns, varying widths. data = [['One', 'Two', 'Three'], ['1', '2', '3']] assert format_pretty_table(data) == dedent(""" --------------------- | One | Two | Three | | 1 | 2 | 3 | --------------------- """).strip() # A table including column names. column_names = ['One', 'Two', 'Three'] data = [['1', '2', '3'], ['a', 'b', 'c']] assert ansi_strip(format_pretty_table(data, column_names)) == dedent(""" --------------------- | One | Two | Three | --------------------- | 1 | 2 | 3 | | a | b | c | --------------------- """).strip() # A table that contains a column with only numeric data (will be right aligned). column_names = ['Just a label', 'Important numbers'] data = [['Row one', '15'], ['Row two', '300']] assert ansi_strip(format_pretty_table(data, column_names)) == dedent(""" ------------------------------------ | Just a label | Important numbers | ------------------------------------ | Row one | 15 | | Row two | 300 | ------------------------------------ """).strip() def test_robust_tables(self): """Test :func:`humanfriendly.tables.format_robust_table()`.""" column_names = ['One', 'Two', 'Three'] data = [['1', '2', '3'], ['a', 'b', 'c']] assert ansi_strip(format_robust_table(data, column_names)) == dedent(""" -------- One: 1 Two: 2 Three: 3 -------- One: a Two: b Three: c -------- """).strip() column_names = ['One', 'Two', 'Three'] data = [['1', '2', '3'], ['a', 'b', 'Here comes a\nmulti line column!']] assert ansi_strip(format_robust_table(data, column_names)) == dedent(""" ------------------ One: 1 Two: 2 Three: 3 ------------------ One: a Two: b Three: Here comes a multi line column! ------------------ """).strip() def test_smart_tables(self): """Test :func:`humanfriendly.tables.format_smart_table()`.""" column_names = ['One', 'Two', 'Three'] data = [['1', '2', '3'], ['a', 'b', 'c']] assert ansi_strip(format_smart_table(data, column_names)) == dedent(""" --------------------- | One | Two | Three | --------------------- | 1 | 2 | 3 | | a | b | c | --------------------- """).strip() column_names = ['One', 'Two', 'Three'] data = [['1', '2', '3'], ['a', 'b', 'Here comes a\nmulti line column!']] assert ansi_strip(format_smart_table(data, column_names)) == dedent(""" ------------------ One: 1 Two: 2 Three: 3 ------------------ One: a Two: b Three: Here comes a multi line column! ------------------ """).strip() def test_rst_tables(self): """Test :func:`humanfriendly.tables.format_rst_table()`.""" # Generate a table with column names. column_names = ['One', 'Two', 'Three'] data = [['1', '2', '3'], ['a', 'b', 'c']] self.assertEqual( format_rst_table(data, column_names), dedent(""" === === ===== One Two Three === === ===== 1 2 3 a b c === === ===== """).rstrip(), ) # Generate a table without column names. data = [['1', '2', '3'], ['a', 'b', 'c']] self.assertEqual( format_rst_table(data), dedent(""" = = = 1 2 3 a b c = = = """).rstrip(), ) def test_concatenate(self): """Test :func:`humanfriendly.text.concatenate()`.""" assert concatenate([]) == '' assert concatenate(['one']) == 'one' assert concatenate(['one', 'two']) == 'one and two' assert concatenate(['one', 'two', 'three']) == 'one, two and three' # Test the 'conjunction' option. assert concatenate(['one', 'two', 'three'], conjunction='or') == 'one, two or three' # Test the 'serial_comma' option. assert concatenate(['one', 'two', 'three'], serial_comma=True) == 'one, two, and three' def test_split(self): """Test :func:`humanfriendly.text.split()`.""" from humanfriendly.text import split self.assertEqual(split(''), []) self.assertEqual(split('foo'), ['foo']) self.assertEqual(split('foo, bar'), ['foo', 'bar']) self.assertEqual(split('foo, bar, baz'), ['foo', 'bar', 'baz']) self.assertEqual(split('foo,bar,baz'), ['foo', 'bar', 'baz']) def test_timer(self): """Test :func:`humanfriendly.Timer`.""" for seconds, text in ((1, '1 second'), (2, '2 seconds'), (60, '1 minute'), (60 * 2, '2 minutes'), (60 * 60, '1 hour'), (60 * 60 * 2, '2 hours'), (60 * 60 * 24, '1 day'), (60 * 60 * 24 * 2, '2 days'), (60 * 60 * 24 * 7, '1 week'), (60 * 60 * 24 * 7 * 2, '2 weeks')): t = Timer(time.time() - seconds) self.assertEqual(round_number(t.elapsed_time, keep_width=True), '%i.00' % seconds) self.assertEqual(str(t), text) # Test rounding to seconds. t = Timer(time.time() - 2.2) self.assertEqual(t.rounded, '2 seconds') # Test automatic timer. automatic_timer = Timer() time.sleep(1) # XXX The following normalize_timestamp(ndigits=0) calls are intended # to compensate for unreliable clock sources in virtual machines # like those encountered on Travis CI, see also: # https://travis-ci.org/xolox/python-humanfriendly/jobs/323944263 self.assertEqual(normalize_timestamp(automatic_timer.elapsed_time, 0), '1.00') # Test resumable timer. resumable_timer = Timer(resumable=True) for i in range(2): with resumable_timer: time.sleep(1) self.assertEqual(normalize_timestamp(resumable_timer.elapsed_time, 0), '2.00') # Make sure Timer.__enter__() returns the timer object. with Timer(resumable=True) as timer: assert timer is not None def test_spinner(self): """Test :func:`humanfriendly.Spinner`.""" stream = StringIO() spinner = Spinner(label='test spinner', total=4, stream=stream, interactive=True) for progress in [1, 2, 3, 4]: spinner.step(progress=progress) time.sleep(0.2) spinner.clear() output = stream.getvalue() output = (output.replace(ANSI_SHOW_CURSOR, '') .replace(ANSI_HIDE_CURSOR, '')) lines = [line for line in output.split(ANSI_ERASE_LINE) if line] self.assertTrue(len(lines) > 0) self.assertTrue(all('test spinner' in ln for ln in lines)) self.assertTrue(all('%' in ln for ln in lines)) self.assertEqual(sorted(set(lines)), sorted(lines)) def test_automatic_spinner(self): """ Test :func:`humanfriendly.AutomaticSpinner`. There's not a lot to test about the :class:`.AutomaticSpinner` class, but by at least running it here we are assured that the code functions on all supported Python versions. :class:`.AutomaticSpinner` is built on top of the :class:`.Spinner` class so at least we also have the tests for the :class:`.Spinner` class to back us up. """ with AutomaticSpinner(label='test spinner'): time.sleep(1) def test_prompt_for_choice(self): """Test :func:`humanfriendly.prompts.prompt_for_choice()`.""" # Choice selection without any options should raise an exception. with self.assertRaises(ValueError): prompt_for_choice([]) # If there's only one option no prompt should be rendered so we expect # the following code to not raise an EOFError exception (despite # connecting standard input to /dev/null). with open(os.devnull) as handle: with PatchedAttribute(sys, 'stdin', handle): only_option = 'only one option (shortcut)' assert prompt_for_choice([only_option]) == only_option # Choice selection by full string match. with PatchedAttribute(prompts, 'interactive_prompt', lambda p: 'foo'): assert prompt_for_choice(['foo', 'bar']) == 'foo' # Choice selection by substring input. with PatchedAttribute(prompts, 'interactive_prompt', lambda p: 'f'): assert prompt_for_choice(['foo', 'bar']) == 'foo' # Choice selection by number. with PatchedAttribute(prompts, 'interactive_prompt', lambda p: '2'): assert prompt_for_choice(['foo', 'bar']) == 'bar' # Choice selection by going with the default. with PatchedAttribute(prompts, 'interactive_prompt', lambda p: ''): assert prompt_for_choice(['foo', 'bar'], default='bar') == 'bar' # Invalid substrings are refused. replies = ['', 'q', 'z'] with PatchedAttribute(prompts, 'interactive_prompt', lambda p: replies.pop(0)): assert prompt_for_choice(['foo', 'bar', 'baz']) == 'baz' # Choice selection by substring input requires an unambiguous substring match. replies = ['a', 'q'] with PatchedAttribute(prompts, 'interactive_prompt', lambda p: replies.pop(0)): assert prompt_for_choice(['foo', 'bar', 'baz', 'qux']) == 'qux' # Invalid numbers are refused. replies = ['42', '2'] with PatchedAttribute(prompts, 'interactive_prompt', lambda p: replies.pop(0)): assert prompt_for_choice(['foo', 'bar', 'baz']) == 'bar' # Test that interactive prompts eventually give up on invalid replies. with PatchedAttribute(prompts, 'interactive_prompt', lambda p: ''): with self.assertRaises(TooManyInvalidReplies): prompt_for_choice(['a', 'b', 'c']) def test_prompt_for_confirmation(self): """Test :func:`humanfriendly.prompts.prompt_for_confirmation()`.""" # Test some (more or less) reasonable replies that indicate agreement. for reply in 'yes', 'Yes', 'YES', 'y', 'Y': with PatchedAttribute(prompts, 'interactive_prompt', lambda p: reply): assert prompt_for_confirmation("Are you sure?") is True # Test some (more or less) reasonable replies that indicate disagreement. for reply in 'no', 'No', 'NO', 'n', 'N': with PatchedAttribute(prompts, 'interactive_prompt', lambda p: reply): assert prompt_for_confirmation("Are you sure?") is False # Test that empty replies select the default choice. for default_choice in True, False: with PatchedAttribute(prompts, 'interactive_prompt', lambda p: ''): assert prompt_for_confirmation("Are you sure?", default=default_choice) is default_choice # Test that a warning is shown when no input nor a default is given. replies = ['', 'y'] with PatchedAttribute(prompts, 'interactive_prompt', lambda p: replies.pop(0)): with CaptureOutput(merged=True) as capturer: assert prompt_for_confirmation("Are you sure?") is True assert "there's no default choice" in capturer.get_text() # Test that the default reply is shown in uppercase. with PatchedAttribute(prompts, 'interactive_prompt', lambda p: 'y'): for default_value, expected_text in (True, 'Y/n'), (False, 'y/N'), (None, 'y/n'): with CaptureOutput(merged=True) as capturer: assert prompt_for_confirmation("Are you sure?", default=default_value) is True assert expected_text in capturer.get_text() # Test that interactive prompts eventually give up on invalid replies. with PatchedAttribute(prompts, 'interactive_prompt', lambda p: ''): with self.assertRaises(TooManyInvalidReplies): prompt_for_confirmation("Are you sure?") def test_prompt_for_input(self): """Test :func:`humanfriendly.prompts.prompt_for_input()`.""" with open(os.devnull) as handle: with PatchedAttribute(sys, 'stdin', handle): # If standard input isn't connected to a terminal the default value should be returned. default_value = "To seek the holy grail!" assert prompt_for_input("What is your quest?", default=default_value) == default_value # If standard input isn't connected to a terminal and no default value # is given the EOFError exception should be propagated to the caller. with self.assertRaises(EOFError): prompt_for_input("What is your favorite color?") def test_cli(self): """Test the command line interface.""" # Test that the usage message is printed by default. returncode, output = run_cli(main) assert 'Usage:' in output # Test that the usage message can be requested explicitly. returncode, output = run_cli(main, '--help') assert 'Usage:' in output # Test handling of invalid command line options. returncode, output = run_cli(main, '--unsupported-option') assert returncode != 0 # Test `humanfriendly --format-number'. returncode, output = run_cli(main, '--format-number=1234567') assert output.strip() == '1,234,567' # Test `humanfriendly --format-size'. random_byte_count = random.randint(1024, 1024 * 1024) returncode, output = run_cli(main, '--format-size=%i' % random_byte_count) assert output.strip() == format_size(random_byte_count) # Test `humanfriendly --format-size --binary'. random_byte_count = random.randint(1024, 1024 * 1024) returncode, output = run_cli(main, '--format-size=%i' % random_byte_count, '--binary') assert output.strip() == format_size(random_byte_count, binary=True) # Test `humanfriendly --format-length'. random_len = random.randint(1024, 1024 * 1024) returncode, output = run_cli(main, '--format-length=%i' % random_len) assert output.strip() == format_length(random_len) random_len = float(random_len) / 12345.6 returncode, output = run_cli(main, '--format-length=%f' % random_len) assert output.strip() == format_length(random_len) # Test `humanfriendly --format-table'. returncode, output = run_cli(main, '--format-table', '--delimiter=\t', input='1\t2\t3\n4\t5\t6\n7\t8\t9') assert output.strip() == dedent(''' ------------- | 1 | 2 | 3 | | 4 | 5 | 6 | | 7 | 8 | 9 | ------------- ''').strip() # Test `humanfriendly --format-timespan'. random_timespan = random.randint(5, 600) returncode, output = run_cli(main, '--format-timespan=%i' % random_timespan) assert output.strip() == format_timespan(random_timespan) # Test `humanfriendly --parse-size'. returncode, output = run_cli(main, '--parse-size=5 KB') assert int(output) == parse_size('5 KB') # Test `humanfriendly --parse-size'. returncode, output = run_cli(main, '--parse-size=5 YiB') assert int(output) == parse_size('5 YB', binary=True) # Test `humanfriendly --parse-length'. returncode, output = run_cli(main, '--parse-length=5 km') assert int(output) == parse_length('5 km') returncode, output = run_cli(main, '--parse-length=1.05 km') assert float(output) == parse_length('1.05 km') # Test `humanfriendly --run-command'. returncode, output = run_cli(main, '--run-command', 'bash', '-c', 'sleep 2 && exit 42') assert returncode == 42 # Test `humanfriendly --demo'. The purpose of this test is # to ensure that the demo runs successfully on all versions # of Python and outputs the expected sections (recognized by # their headings) without triggering exceptions. This was # written as a regression test after issue #28 was reported: # https://github.com/xolox/python-humanfriendly/issues/28 returncode, output = run_cli(main, '--demo') assert returncode == 0 lines = [ansi_strip(ln) for ln in output.splitlines()] assert "Text styles:" in lines assert "Foreground colors:" in lines assert "Background colors:" in lines assert "256 color mode (standard colors):" in lines assert "256 color mode (high-intensity colors):" in lines assert "256 color mode (216 colors):" in lines assert "256 color mode (gray scale colors):" in lines def test_ansi_style(self): """Test :func:`humanfriendly.terminal.ansi_style()`.""" assert ansi_style(bold=True) == '%s1%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(faint=True) == '%s2%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(italic=True) == '%s3%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(underline=True) == '%s4%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(inverse=True) == '%s7%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(strike_through=True) == '%s9%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(color='blue') == '%s34%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(background='blue') == '%s44%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(color='blue', bright=True) == '%s94%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(color=214) == '%s38;5;214%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(background=214) == '%s39;5;214%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(color=(0, 0, 0)) == '%s38;2;0;0;0%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(color=(255, 255, 255)) == '%s38;2;255;255;255%s' % (ANSI_CSI, ANSI_SGR) assert ansi_style(background=(50, 100, 150)) == '%s48;2;50;100;150%s' % (ANSI_CSI, ANSI_SGR) with self.assertRaises(ValueError): ansi_style(color='unknown') def test_ansi_width(self): """Test :func:`humanfriendly.terminal.ansi_width()`.""" text = "Whatever" # Make sure ansi_width() works as expected on strings without ANSI escape sequences. assert len(text) == ansi_width(text) # Wrap a text in ANSI escape sequences and make sure ansi_width() treats it as expected. wrapped = ansi_wrap(text, bold=True) # Make sure ansi_wrap() changed the text. assert wrapped != text # Make sure ansi_wrap() added additional bytes. assert len(wrapped) > len(text) # Make sure the result of ansi_width() stays the same. assert len(text) == ansi_width(wrapped) def test_ansi_wrap(self): """Test :func:`humanfriendly.terminal.ansi_wrap()`.""" text = "Whatever" # Make sure ansi_wrap() does nothing when no keyword arguments are given. assert text == ansi_wrap(text) # Make sure ansi_wrap() starts the text with the CSI sequence. assert ansi_wrap(text, bold=True).startswith(ANSI_CSI) # Make sure ansi_wrap() ends the text by resetting the ANSI styles. assert ansi_wrap(text, bold=True).endswith(ANSI_RESET) def test_html_to_ansi(self): """Test the :func:`humanfriendly.terminal.html_to_ansi()` function.""" assert html_to_ansi("Just some plain text") == "Just some plain text" # Hyperlinks. assert html_to_ansi('<a href="https://python.org">python.org</a>') == \ '\x1b[0m\x1b[4;94mpython.org\x1b[0m (\x1b[0m\x1b[4;94mhttps://python.org\x1b[0m)' # Make sure `mailto:' prefixes are stripped (they're not at all useful in a terminal). assert html_to_ansi('<a href="mailto:peter@peterodding.com">peter@peterodding.com</a>') == \ '\x1b[0m\x1b[4;94mpeter@peterodding.com\x1b[0m' # Bold text. assert html_to_ansi("Let's try <b>bold</b>") == "Let's try \x1b[0m\x1b[1mbold\x1b[0m" assert html_to_ansi("Let's try <span style=\"font-weight: bold\">bold</span>") == \ "Let's try \x1b[0m\x1b[1mbold\x1b[0m" # Italic text. assert html_to_ansi("Let's try <i>italic</i>") == \ "Let's try \x1b[0m\x1b[3mitalic\x1b[0m" assert html_to_ansi("Let's try <span style=\"font-style: italic\">italic</span>") == \ "Let's try \x1b[0m\x1b[3mitalic\x1b[0m" # Underlined text. assert html_to_ansi("Let's try <ins>underline</ins>") == \ "Let's try \x1b[0m\x1b[4munderline\x1b[0m" assert html_to_ansi("Let's try <span style=\"text-decoration: underline\">underline</span>") == \ "Let's try \x1b[0m\x1b[4munderline\x1b[0m" # Strike-through text. assert html_to_ansi("Let's try <s>strike-through</s>") == \ "Let's try \x1b[0m\x1b[9mstrike-through\x1b[0m" assert html_to_ansi("Let's try <span style=\"text-decoration: line-through\">strike-through</span>") == \ "Let's try \x1b[0m\x1b[9mstrike-through\x1b[0m" # Pre-formatted text. assert html_to_ansi("Let's try <code>pre-formatted</code>") == \ "Let's try \x1b[0m\x1b[33mpre-formatted\x1b[0m" # Text colors (with a 6 digit hexadecimal color value). assert html_to_ansi("Let's try <span style=\"color: #AABBCC\">text colors</s>") == \ "Let's try \x1b[0m\x1b[38;2;170;187;204mtext colors\x1b[0m" # Background colors (with an rgb(N, N, N) expression). assert html_to_ansi("Let's try <span style=\"background-color: rgb(50, 50, 50)\">background colors</s>") == \ "Let's try \x1b[0m\x1b[48;2;50;50;50mbackground colors\x1b[0m" # Line breaks. assert html_to_ansi("Let's try some<br>line<br>breaks") == \ "Let's try some\nline\nbreaks" # Check that decimal entities are decoded. assert html_to_ansi("&") == "&" # Check that named entities are decoded. assert html_to_ansi("&") == "&" assert html_to_ansi(">") == ">" assert html_to_ansi("<") == "<" # Check that hexadecimal entities are decoded. assert html_to_ansi("&") == "&" # Check that the text callback is actually called. def callback(text): return text.replace(':wink:', ';-)') assert ':wink:' not in html_to_ansi('<b>:wink:</b>', callback=callback) # Check that the text callback doesn't process preformatted text. assert ':wink:' in html_to_ansi('<code>:wink:</code>', callback=callback) # Try a somewhat convoluted but nevertheless real life example from my # personal chat archives that causes humanfriendly releases 4.15 and # 4.15.1 to raise an exception. assert html_to_ansi(u''' Tweakers zit er idd nog steeds:<br><br> peter@peter-work> curl -s <a href="tweakers.net">tweakers.net</a> | grep -i hosting<br> <a href="<a href="http://www.true.nl/webhosting/">http://www.true.nl/webhosting/</a>" rel="external" id="true" title="Hosting door True"></a><br> Hosting door <a href="<a href="http://www.true.nl/vps/">http://www.true.nl/vps/</a>" title="VPS hosting" rel="external">True</a> ''') def test_generate_output(self): """Test the :func:`humanfriendly.terminal.output()` function.""" text = "Standard output generated by output()" with CaptureOutput(merged=False) as capturer: output(text) self.assertEqual([text], capturer.stdout.get_lines()) self.assertEqual([], capturer.stderr.get_lines()) def test_generate_message(self): """Test the :func:`humanfriendly.terminal.message()` function.""" text = "Standard error generated by message()" with CaptureOutput(merged=False) as capturer: message(text) self.assertEqual([], capturer.stdout.get_lines()) self.assertEqual([text], capturer.stderr.get_lines()) def test_generate_warning(self): """Test the :func:`humanfriendly.terminal.warning()` function.""" from capturer import CaptureOutput text = "Standard error generated by warning()" with CaptureOutput(merged=False) as capturer: warning(text) self.assertEqual([], capturer.stdout.get_lines()) self.assertEqual([ansi_wrap(text, color='red')], self.ignore_coverage_warning(capturer.stderr)) def ignore_coverage_warning(self, stream): """ Filter out coverage.py warning from standard error. This is intended to remove the following line from the lines captured on the standard error stream: Coverage.py warning: No data was collected. (no-data-collected) """ return [line for line in stream.get_lines() if 'no-data-collected' not in line] def test_clean_output(self): """Test :func:`humanfriendly.terminal.clean_terminal_output()`.""" # Simple output should pass through unharmed (single line). assert clean_terminal_output('foo') == ['foo'] # Simple output should pass through unharmed (multiple lines). assert clean_terminal_output('foo\nbar') == ['foo', 'bar'] # Carriage returns and preceding substrings are removed. assert clean_terminal_output('foo\rbar\nbaz') == ['bar', 'baz'] # Carriage returns move the cursor to the start of the line without erasing text. assert clean_terminal_output('aaa\rab') == ['aba'] # Backspace moves the cursor one position back without erasing text. assert clean_terminal_output('aaa\b\bb') == ['aba'] # Trailing empty lines should be stripped. assert clean_terminal_output('foo\nbar\nbaz\n\n\n') == ['foo', 'bar', 'baz'] def test_find_terminal_size(self): """Test :func:`humanfriendly.terminal.find_terminal_size()`.""" lines, columns = find_terminal_size() # We really can't assert any minimum or maximum values here because it # simply doesn't make any sense; it's impossible for me to anticipate # on what environments this test suite will run in the future. assert lines > 0 assert columns > 0 # The find_terminal_size_using_ioctl() function is the default # implementation and it will likely work fine. This makes it hard to # test the fall back code paths though. However there's an easy way to # make find_terminal_size_using_ioctl() fail ... saved_stdin = sys.stdin saved_stdout = sys.stdout saved_stderr = sys.stderr try: # What do you mean this is brute force?! ;-) sys.stdin = StringIO() sys.stdout = StringIO() sys.stderr = StringIO() # Now find_terminal_size_using_ioctl() should fail even though # find_terminal_size_using_stty() might work fine. lines, columns = find_terminal_size() assert lines > 0 assert columns > 0 # There's also an ugly way to make `stty size' fail: The # subprocess.Popen class uses os.execvp() underneath, so if we # clear the $PATH it will break. saved_path = os.environ['PATH'] try: os.environ['PATH'] = '' # Now find_terminal_size_using_stty() should fail. lines, columns = find_terminal_size() assert lines > 0 assert columns > 0 finally: os.environ['PATH'] = saved_path finally: sys.stdin = saved_stdin sys.stdout = saved_stdout sys.stderr = saved_stderr def test_terminal_capabilities(self): """Test the functions that check for terminal capabilities.""" from capturer import CaptureOutput for test_stream in connected_to_terminal, terminal_supports_colors: # This test suite should be able to run interactively as well as # non-interactively, so we can't expect or demand that standard streams # will always be connected to a terminal. Fortunately Capturer enables # us to fake it :-). for stream in sys.stdout, sys.stderr: with CaptureOutput(): assert test_stream(stream) # Test something that we know can never be a terminal. with open(os.devnull) as handle: assert not test_stream(handle) # Verify that objects without isatty() don't raise an exception. assert not test_stream(object()) def test_show_pager(self): """Test :func:`humanfriendly.terminal.show_pager()`.""" original_pager = os.environ.get('PAGER', None) try: # We specifically avoid `less' because it would become awkward to # run the test suite in an interactive terminal :-). os.environ['PAGER'] = 'cat' # Generate a significant amount of random text spread over multiple # lines that we expect to be reported literally on the terminal. random_text = "\n".join(random_string(25) for i in range(50)) # Run the pager command and validate the output. with CaptureOutput() as capturer: show_pager(random_text) assert random_text in capturer.get_text() 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_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_find_meta_variables(self): """Test :func:`humanfriendly.usage.find_meta_variables()`.""" assert sorted(find_meta_variables(""" Here's one example: --format-number=VALUE Here's another example: --format-size=BYTES A final example: --format-timespan=SECONDS This line doesn't contain a META variable. """)) == sorted(['VALUE', 'BYTES', 'SECONDS']) def test_parse_usage_simple(self): """Test :func:`humanfriendly.usage.parse_usage()` (a simple case).""" introduction, options = self.preprocess_parse_result(""" Usage: my-fancy-app [OPTIONS] Boring description. Supported options: -h, --help Show this message and exit. """) # The following fragments are (expected to be) part of the introduction. assert "Usage: my-fancy-app [OPTIONS]" in introduction assert "Boring description." in introduction assert "Supported options:" in introduction # The following fragments are (expected to be) part of the documented options. assert "-h, --help" in options assert "Show this message and exit." in options def test_parse_usage_tricky(self): """Test :func:`humanfriendly.usage.parse_usage()` (a tricky case).""" introduction, options = self.preprocess_parse_result(""" Usage: my-fancy-app [OPTIONS] Here's the introduction to my-fancy-app. Some of the lines in the introduction start with a command line option just to confuse the parsing algorithm :-) For example --an-awesome-option is still part of the introduction. Supported options: -a, --an-awesome-option Explanation why this is an awesome option. -b, --a-boring-option Explanation why this is a boring option. """) # The following fragments are (expected to be) part of the introduction. assert "Usage: my-fancy-app [OPTIONS]" in introduction assert any('still part of the introduction' in p for p in introduction) assert "Supported options:" in introduction # The following fragments are (expected to be) part of the documented options. assert "-a, --an-awesome-option" in options assert "Explanation why this is an awesome option." in options assert "-b, --a-boring-option" in options assert "Explanation why this is a boring option." in options def test_parse_usage_commas(self): """Test :func:`humanfriendly.usage.parse_usage()` against option labels containing commas.""" introduction, options = self.preprocess_parse_result(""" Usage: my-fancy-app [OPTIONS] Some introduction goes here. Supported options: -f, --first-option Explanation of first option. -s, --second-option=WITH,COMMA This should be a separate option's description. """) # The following fragments are (expected to be) part of the introduction. assert "Usage: my-fancy-app [OPTIONS]" in introduction assert "Some introduction goes here." in introduction assert "Supported options:" in introduction # The following fragments are (expected to be) part of the documented options. assert "-f, --first-option" in options assert "Explanation of first option." in options assert "-s, --second-option=WITH,COMMA" in options assert "This should be a separate option's description." in options def preprocess_parse_result(self, text): """Ignore leading/trailing whitespace in usage parsing tests.""" return tuple([p.strip() for p in r] for r in parse_usage(dedent(text))) def test_format_usage(self): """Test :func:`humanfriendly.usage.format_usage()`.""" # Test that options are highlighted. usage_text = "Just one --option" formatted_text = format_usage(usage_text) assert len(formatted_text) > len(usage_text) assert formatted_text.startswith("Just one ") # Test that the "Usage: ..." line is highlighted. usage_text = "Usage: humanfriendly [OPTIONS]" formatted_text = format_usage(usage_text) assert len(formatted_text) > len(usage_text) assert usage_text in formatted_text assert not formatted_text.startswith(usage_text) # Test that meta variables aren't erroneously highlighted. usage_text = ( "--valid-option=VALID_METAVAR\n" "VALID_METAVAR is bogus\n" "INVALID_METAVAR should not be highlighted\n" ) formatted_text = format_usage(usage_text) formatted_lines = formatted_text.splitlines() # Make sure the meta variable in the second line is highlighted. assert ANSI_CSI in formatted_lines[1] # Make sure the meta variable in the third line isn't highlighted. assert ANSI_CSI not in formatted_lines[2] def test_render_usage(self): """Test :func:`humanfriendly.usage.render_usage()`.""" assert render_usage("Usage: some-command WITH ARGS") == "**Usage:** `some-command WITH ARGS`" assert render_usage("Supported options:") == "**Supported options:**" assert 'code-block' in render_usage(dedent(""" Here comes a shell command: $ echo test test """)) assert all(token in render_usage(dedent(""" Supported options: -n, --dry-run Don't change anything. """)) for token in ('`-n`', '`--dry-run`')) def test_deprecated_args(self): """Test the deprecated_args() decorator function.""" @deprecated_args('foo', 'bar') def test_function(**options): assert options['foo'] == 'foo' assert options.get('bar') in (None, 'bar') return 42 fake_fn = MagicMock() with PatchedAttribute(warnings, 'warn', fake_fn): assert test_function('foo', 'bar') == 42 with self.assertRaises(TypeError): test_function('foo', 'bar', 'baz') assert fake_fn.was_called def test_alias_proxy_deprecation_warning(self): """Test that the DeprecationProxy class emits deprecation warnings.""" fake_fn = MagicMock() with PatchedAttribute(warnings, 'warn', fake_fn): module = sys.modules[__name__] aliases = dict(concatenate='humanfriendly.text.concatenate') proxy = DeprecationProxy(module, aliases) assert proxy.concatenate == concatenate assert fake_fn.was_called def test_alias_proxy_sphinx_compensation(self): """Test that the DeprecationProxy class emits deprecation warnings.""" with PatchedItem(sys.modules, 'sphinx', types.ModuleType('sphinx')): define_aliases(__name__, concatenate='humanfriendly.text.concatenate') assert "concatenate" in dir(sys.modules[__name__]) assert "concatenate" in get_aliases(__name__) def test_alias_proxy_sphinx_integration(self): """Test that aliases can be injected into generated documentation.""" module = sys.modules[__name__] define_aliases(__name__, concatenate='humanfriendly.text.concatenate') lines = module.__doc__.splitlines() deprecation_note_callback(app=None, what=None, name=None, obj=module, options=None, lines=lines) # Check that something was injected. assert "\n".join(lines) != module.__doc__ def test_sphinx_customizations(self): """Test the :mod:`humanfriendly.sphinx` module.""" class FakeApp(object): def __init__(self): self.callbacks = {} self.roles = {} def __documented_special_method__(self): """Documented unofficial special method.""" pass def __undocumented_special_method__(self): # Intentionally not documented :-). pass def add_role(self, name, callback): self.roles[name] = callback def connect(self, event, callback): self.callbacks.setdefault(event, []).append(callback) def bogus_usage(self): """Usage: This is not supposed to be reformatted!""" pass # Test event callback registration. fake_app = FakeApp() setup(fake_app) assert man_role == fake_app.roles['man'] assert pypi_role == fake_app.roles['pypi'] assert deprecation_note_callback in fake_app.callbacks['autodoc-process-docstring'] assert special_methods_callback in fake_app.callbacks['autodoc-skip-member'] assert usage_message_callback in fake_app.callbacks['autodoc-process-docstring'] # Test that `special methods' which are documented aren't skipped. assert special_methods_callback( app=None, what=None, name=None, obj=FakeApp.__documented_special_method__, skip=True, options=None, ) is False # Test that `special methods' which are undocumented are skipped. assert special_methods_callback( app=None, what=None, name=None, obj=FakeApp.__undocumented_special_method__, skip=True, options=None, ) is True # Test formatting of usage messages. obj/lines from humanfriendly import cli, sphinx # We expect the docstring in the `cli' module to be reformatted # (because it contains a usage message in the expected format). assert self.docstring_is_reformatted(cli) # We don't expect the docstring in the `sphinx' module to be # reformatted (because it doesn't contain a usage message). assert not self.docstring_is_reformatted(sphinx) # We don't expect the docstring of the following *method* to be # reformatted because only *module* docstrings should be reformatted. assert not self.docstring_is_reformatted(fake_app.bogus_usage) def docstring_is_reformatted(self, entity): """Check whether :func:`.usage_message_callback()` reformats a module's docstring.""" lines = trim_empty_lines(entity.__doc__).splitlines() saved_lines = list(lines) usage_message_callback( app=None, what=None, name=None, obj=entity, options=None, lines=lines, ) return lines != saved_lines def normalize_timestamp(value, ndigits=1): """ Round timestamps to the given number of digits. This helps to make the test suite less sensitive to timing issues caused by multitasking, processor scheduling, etc. """ return '%.2f' % round(float(value), ndigits=ndigits)