sam/voice_bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add read me

Browse Source
This commit is contained in:
Sam Rolfe
2026-01-09 10:28:44 +11:00
commit edaf914b73
13417 changed files with 2952119 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

838
venv/lib/python3.12/site-packages/humanfriendly/__init__.py Normal file
View File

@@ -0,0 +1,838 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: September 17, 2021
# URL: https://humanfriendly.readthedocs.io
"""The main module of the `humanfriendly` package."""
# Standard library modules.
import collections
import datetime
import decimal
import numbers
import os
import os.path
import re
import time
# Modules included in our package.
from humanfriendly.compat import is_string, monotonic
from humanfriendly.deprecation import define_aliases
from humanfriendly.text import concatenate, format, pluralize, tokenize
# Public identifiers that require documentation.
__all__ = (
'CombinedUnit',
'InvalidDate',
'InvalidLength',
'InvalidSize',
'InvalidTimespan',
'SizeUnit',
'Timer',
'__version__',
'coerce_boolean',
'coerce_pattern',
'coerce_seconds',
'disk_size_units',
'format_length',
'format_number',
'format_path',
'format_size',
'format_timespan',
'length_size_units',
'parse_date',
'parse_length',
'parse_path',
'parse_size',
'parse_timespan',
'round_number',
'time_units',
)
# Semi-standard module versioning.
__version__ = '10.0'
# Named tuples to define units of size.
SizeUnit = collections.namedtuple('SizeUnit', 'divider, symbol, name')
CombinedUnit = collections.namedtuple('CombinedUnit', 'decimal, binary')
# Common disk size units in binary (base-2) and decimal (base-10) multiples.
disk_size_units = (
CombinedUnit(SizeUnit(1000**1, 'KB', 'kilobyte'), SizeUnit(1024**1, 'KiB', 'kibibyte')),
CombinedUnit(SizeUnit(1000**2, 'MB', 'megabyte'), SizeUnit(1024**2, 'MiB', 'mebibyte')),
CombinedUnit(SizeUnit(1000**3, 'GB', 'gigabyte'), SizeUnit(1024**3, 'GiB', 'gibibyte')),
CombinedUnit(SizeUnit(1000**4, 'TB', 'terabyte'), SizeUnit(1024**4, 'TiB', 'tebibyte')),
CombinedUnit(SizeUnit(1000**5, 'PB', 'petabyte'), SizeUnit(1024**5, 'PiB', 'pebibyte')),
CombinedUnit(SizeUnit(1000**6, 'EB', 'exabyte'), SizeUnit(1024**6, 'EiB', 'exbibyte')),
CombinedUnit(SizeUnit(1000**7, 'ZB', 'zettabyte'), SizeUnit(1024**7, 'ZiB', 'zebibyte')),
CombinedUnit(SizeUnit(1000**8, 'YB', 'yottabyte'), SizeUnit(1024**8, 'YiB', 'yobibyte')),
)
# Common length size units, used for formatting and parsing.
length_size_units = (dict(prefix='nm', divider=1e-09, singular='nm', plural='nm'),
dict(prefix='mm', divider=1e-03, singular='mm', plural='mm'),
dict(prefix='cm', divider=1e-02, singular='cm', plural='cm'),
dict(prefix='m', divider=1, singular='metre', plural='metres'),
dict(prefix='km', divider=1000, singular='km', plural='km'))
# Common time units, used for formatting of time spans.
time_units = (dict(divider=1e-9, singular='nanosecond', plural='nanoseconds', abbreviations=['ns']),
dict(divider=1e-6, singular='microsecond', plural='microseconds', abbreviations=['us']),
dict(divider=1e-3, singular='millisecond', plural='milliseconds', abbreviations=['ms']),
dict(divider=1, singular='second', plural='seconds', abbreviations=['s', 'sec', 'secs']),
dict(divider=60, singular='minute', plural='minutes', abbreviations=['m', 'min', 'mins']),
dict(divider=60 * 60, singular='hour', plural='hours', abbreviations=['h']),
dict(divider=60 * 60 * 24, singular='day', plural='days', abbreviations=['d']),
dict(divider=60 * 60 * 24 * 7, singular='week', plural='weeks', abbreviations=['w']),
dict(divider=60 * 60 * 24 * 7 * 52, singular='year', plural='years', abbreviations=['y']))
def coerce_boolean(value):
"""
Coerce any value to a boolean.
:param value: Any Python value. If the value is a string:
- The strings '1', 'yes', 'true' and 'on' are coerced to :data:`True`.
- The strings '0', 'no', 'false' and 'off' are coerced to :data:`False`.
- Other strings raise an exception.
Other Python values are coerced using :class:`bool`.
:returns: A proper boolean value.
:raises: :exc:`exceptions.ValueError` when the value is a string but
cannot be coerced with certainty.
"""
if is_string(value):
normalized = value.strip().lower()
if normalized in ('1', 'yes', 'true', 'on'):
return True
elif normalized in ('0', 'no', 'false', 'off', ''):
return False
else:
msg = "Failed to coerce string to boolean! (%r)"
raise ValueError(format(msg, value))
else:
return bool(value)
def coerce_pattern(value, flags=0):
"""
Coerce strings to compiled regular expressions.
:param value: A string containing a regular expression pattern
or a compiled regular expression.
:param flags: The flags used to compile the pattern (an integer).
:returns: A compiled regular expression.
:raises: :exc:`~exceptions.ValueError` when `value` isn't a string
and also isn't a compiled regular expression.
"""
if is_string(value):
value = re.compile(value, flags)
else:
empty_pattern = re.compile('')
pattern_type = type(empty_pattern)
if not isinstance(value, pattern_type):
msg = "Failed to coerce value to compiled regular expression! (%r)"
raise ValueError(format(msg, value))
return value
def coerce_seconds(value):
"""
Coerce a value to the number of seconds.
:param value: An :class:`int`, :class:`float` or
:class:`datetime.timedelta` object.
:returns: An :class:`int` or :class:`float` value.
When `value` is a :class:`datetime.timedelta` object the
:meth:`~datetime.timedelta.total_seconds()` method is called.
"""
if isinstance(value, datetime.timedelta):
return value.total_seconds()
if not isinstance(value, numbers.Number):
msg = "Failed to coerce value to number of seconds! (%r)"
raise ValueError(format(msg, value))
return value
def format_size(num_bytes, keep_width=False, binary=False):
"""
Format a byte count as a human readable file size.
:param num_bytes: The size to format in bytes (an integer).
:param keep_width: :data:`True` if trailing zeros should not be stripped,
:data:`False` if they can be stripped.
:param binary: :data:`True` to use binary multiples of bytes (base-2),
:data:`False` to use decimal multiples of bytes (base-10).
:returns: The corresponding human readable file size (a string).
This function knows how to format sizes in bytes, kilobytes, megabytes,
gigabytes, terabytes and petabytes. Some examples:
>>> from humanfriendly import format_size
>>> format_size(0)
'0 bytes'
>>> format_size(1)
'1 byte'
>>> format_size(5)
'5 bytes'
> format_size(1000)
'1 KB'
> format_size(1024, binary=True)
'1 KiB'
>>> format_size(1000 ** 3 * 4)
'4 GB'
"""
for unit in reversed(disk_size_units):
if num_bytes >= unit.binary.divider and binary:
number = round_number(float(num_bytes) / unit.binary.divider, keep_width=keep_width)
return pluralize(number, unit.binary.symbol, unit.binary.symbol)
elif num_bytes >= unit.decimal.divider and not binary:
number = round_number(float(num_bytes) / unit.decimal.divider, keep_width=keep_width)
return pluralize(number, unit.decimal.symbol, unit.decimal.symbol)
return pluralize(num_bytes, 'byte')
def parse_size(size, binary=False):
"""
Parse a human readable data size and return the number of bytes.
:param size: The human readable file size to parse (a string).
:param binary: :data:`True` to use binary multiples of bytes (base-2) for
ambiguous unit symbols and names, :data:`False` to use
decimal multiples of bytes (base-10).
:returns: The corresponding size in bytes (an integer).
:raises: :exc:`InvalidSize` when the input can't be parsed.
This function knows how to parse sizes in bytes, kilobytes, megabytes,
gigabytes, terabytes and petabytes. Some examples:
>>> from humanfriendly import parse_size
>>> parse_size('42')
42
>>> parse_size('13b')
13
>>> parse_size('5 bytes')
5
>>> parse_size('1 KB')
1000
>>> parse_size('1 kilobyte')
1000
>>> parse_size('1 KiB')
1024
>>> parse_size('1 KB', binary=True)
1024
>>> parse_size('1.5 GB')
1500000000
>>> parse_size('1.5 GB', binary=True)
1610612736
"""
tokens = tokenize(size)
if tokens and isinstance(tokens[0], numbers.Number):
# Get the normalized unit (if any) from the tokenized input.
normalized_unit = tokens[1].lower() if len(tokens) == 2 and is_string(tokens[1]) else ''
# If the input contains only a number, it's assumed to be the number of
# bytes. The second token can also explicitly reference the unit bytes.
if len(tokens) == 1 or normalized_unit.startswith('b'):
return int(tokens[0])
# Otherwise we expect two tokens: A number and a unit.
if normalized_unit:
# Convert plural units to singular units, for details:
# https://github.com/xolox/python-humanfriendly/issues/26
normalized_unit = normalized_unit.rstrip('s')
for unit in disk_size_units:
# First we check for unambiguous symbols (KiB, MiB, GiB, etc)
# and names (kibibyte, mebibyte, gibibyte, etc) because their
# handling is always the same.
if normalized_unit in (unit.binary.symbol.lower(), unit.binary.name.lower()):
return int(tokens[0] * unit.binary.divider)
# Now we will deal with ambiguous prefixes (K, M, G, etc),
# symbols (KB, MB, GB, etc) and names (kilobyte, megabyte,
# gigabyte, etc) according to the caller's preference.
if (normalized_unit in (unit.decimal.symbol.lower(), unit.decimal.name.lower()) or
normalized_unit.startswith(unit.decimal.symbol[0].lower())):
return int(tokens[0] * (unit.binary.divider if binary else unit.decimal.divider))
# We failed to parse the size specification.
msg = "Failed to parse size! (input %r was tokenized as %r)"
raise InvalidSize(format(msg, size, tokens))
def format_length(num_metres, keep_width=False):
"""
Format a metre count as a human readable length.
:param num_metres: The length to format in metres (float / integer).
:param keep_width: :data:`True` if trailing zeros should not be stripped,
:data:`False` if they can be stripped.
:returns: The corresponding human readable length (a string).
This function supports ranges from nanometres to kilometres.
Some examples:
>>> from humanfriendly import format_length
>>> format_length(0)
'0 metres'
>>> format_length(1)
'1 metre'
>>> format_length(5)
'5 metres'
>>> format_length(1000)
'1 km'
>>> format_length(0.004)
'4 mm'
"""
for unit in reversed(length_size_units):
if num_metres >= unit['divider']:
number = round_number(float(num_metres) / unit['divider'], keep_width=keep_width)
return pluralize(number, unit['singular'], unit['plural'])
return pluralize(num_metres, 'metre')
def parse_length(length):
"""
Parse a human readable length and return the number of metres.
:param length: The human readable length to parse (a string).
:returns: The corresponding length in metres (a float).
:raises: :exc:`InvalidLength` when the input can't be parsed.
Some examples:
>>> from humanfriendly import parse_length
>>> parse_length('42')
42
>>> parse_length('1 km')
1000
>>> parse_length('5mm')
0.005
>>> parse_length('15.3cm')
0.153
"""
tokens = tokenize(length)
if tokens and isinstance(tokens[0], numbers.Number):
# If the input contains only a number, it's assumed to be the number of metres.
if len(tokens) == 1:
return tokens[0]
# Otherwise we expect to find two tokens: A number and a unit.
if len(tokens) == 2 and is_string(tokens[1]):
normalized_unit = tokens[1].lower()
# Try to match the first letter of the unit.
for unit in length_size_units:
if normalized_unit.startswith(unit['prefix']):
return tokens[0] * unit['divider']
# We failed to parse the length specification.
msg = "Failed to parse length! (input %r was tokenized as %r)"
raise InvalidLength(format(msg, length, tokens))
def format_number(number, num_decimals=2):
"""
Format a number as a string including thousands separators.
:param number: The number to format (a number like an :class:`int`,
:class:`long` or :class:`float`).
:param num_decimals: The number of decimals to render (2 by default). If no
decimal places are required to represent the number
they will be omitted regardless of this argument.
:returns: The formatted number (a string).
This function is intended to make it easier to recognize the order of size
of the number being formatted.
Here's an example:
>>> from humanfriendly import format_number
>>> print(format_number(6000000))
6,000,000
> print(format_number(6000000000.42))
6,000,000,000.42
> print(format_number(6000000000.42, num_decimals=0))
6,000,000,000
"""
integer_part, _, decimal_part = str(float(number)).partition('.')
negative_sign = integer_part.startswith('-')
reversed_digits = ''.join(reversed(integer_part.lstrip('-')))
parts = []
while reversed_digits:
parts.append(reversed_digits[:3])
reversed_digits = reversed_digits[3:]
formatted_number = ''.join(reversed(','.join(parts)))
decimals_to_add = decimal_part[:num_decimals].rstrip('0')
if decimals_to_add:
formatted_number += '.' + decimals_to_add
if negative_sign:
formatted_number = '-' + formatted_number
return formatted_number
def round_number(count, keep_width=False):
"""
Round a floating point number to two decimal places in a human friendly format.
:param count: The number to format.
:param keep_width: :data:`True` if trailing zeros should not be stripped,
:data:`False` if they can be stripped.
:returns: The formatted number as a string. If no decimal places are
required to represent the number, they will be omitted.
The main purpose of this function is to be used by functions like
:func:`format_length()`, :func:`format_size()` and
:func:`format_timespan()`.
Here are some examples:
>>> from humanfriendly import round_number
>>> round_number(1)
'1'
>>> round_number(math.pi)
'3.14'
>>> round_number(5.001)
'5'
"""
text = '%.2f' % float(count)
if not keep_width:
text = re.sub('0+$', '', text)
text = re.sub(r'\.$', '', text)
return text
def format_timespan(num_seconds, detailed=False, max_units=3):
"""
Format a timespan in seconds as a human readable string.
:param num_seconds: Any value accepted by :func:`coerce_seconds()`.
:param detailed: If :data:`True` milliseconds are represented separately
instead of being represented as fractional seconds
(defaults to :data:`False`).
:param max_units: The maximum number of units to show in the formatted time
span (an integer, defaults to three).
:returns: The formatted timespan as a string.
:raise: See :func:`coerce_seconds()`.
Some examples:
>>> from humanfriendly import format_timespan
>>> format_timespan(0)
'0 seconds'
>>> format_timespan(1)
'1 second'
>>> import math
>>> format_timespan(math.pi)
'3.14 seconds'
>>> hour = 60 * 60
>>> day = hour * 24
>>> week = day * 7
>>> format_timespan(week * 52 + day * 2 + hour * 3)
'1 year, 2 days and 3 hours'
"""
num_seconds = coerce_seconds(num_seconds)
if num_seconds < 60 and not detailed:
# Fast path.
return pluralize(round_number(num_seconds), 'second')
else:
# Slow path.
result = []
num_seconds = decimal.Decimal(str(num_seconds))
relevant_units = list(reversed(time_units[0 if detailed else 3:]))
for unit in relevant_units:
# Extract the unit count from the remaining time.
divider = decimal.Decimal(str(unit['divider']))
count = num_seconds / divider
num_seconds %= divider
# Round the unit count appropriately.
if unit != relevant_units[-1]:
# Integer rounding for all but the smallest unit.
count = int(count)
else:
# Floating point rounding for the smallest unit.
count = round_number(count)
# Only include relevant units in the result.
if count not in (0, '0'):
result.append(pluralize(count, unit['singular'], unit['plural']))
if len(result) == 1:
# A single count/unit combination.
return result[0]
else:
if not detailed:
# Remove `insignificant' data from the formatted timespan.
result = result[:max_units]
# Format the timespan in a readable way.
return concatenate(result)
def parse_timespan(timespan):
"""
Parse a "human friendly" timespan into the number of seconds.
:param value: A string like ``5h`` (5 hours), ``10m`` (10 minutes) or
``42s`` (42 seconds).
:returns: The number of seconds as a floating point number.
:raises: :exc:`InvalidTimespan` when the input can't be parsed.
Note that the :func:`parse_timespan()` function is not meant to be the
"mirror image" of the :func:`format_timespan()` function. Instead it's
meant to allow humans to easily and succinctly specify a timespan with a
minimal amount of typing. It's very useful to accept easy to write time
spans as e.g. command line arguments to programs.
The time units (and abbreviations) supported by this function are:
- ms, millisecond, milliseconds
- s, sec, secs, second, seconds
- m, min, mins, minute, minutes
- h, hour, hours
- d, day, days
- w, week, weeks
- y, year, years
Some examples:
>>> from humanfriendly import parse_timespan
>>> parse_timespan('42')
42.0
>>> parse_timespan('42s')
42.0
>>> parse_timespan('1m')
60.0
>>> parse_timespan('1h')
3600.0
>>> parse_timespan('1d')
86400.0
"""
tokens = tokenize(timespan)
if tokens and isinstance(tokens[0], numbers.Number):
# If the input contains only a number, it's assumed to be the number of seconds.
if len(tokens) == 1:
return float(tokens[0])
# Otherwise we expect to find two tokens: A number and a unit.
if len(tokens) == 2 and is_string(tokens[1]):
normalized_unit = tokens[1].lower()
for unit in time_units:
if (normalized_unit == unit['singular'] or
normalized_unit == unit['plural'] or
normalized_unit in unit['abbreviations']):
return float(tokens[0]) * unit['divider']
# We failed to parse the timespan specification.
msg = "Failed to parse timespan! (input %r was tokenized as %r)"
raise InvalidTimespan(format(msg, timespan, tokens))
def parse_date(datestring):
"""
Parse a date/time string into a tuple of integers.
:param datestring: The date/time string to parse.
:returns: A tuple with the numbers ``(year, month, day, hour, minute,
second)`` (all numbers are integers).
:raises: :exc:`InvalidDate` when the date cannot be parsed.
Supported date/time formats:
- ``YYYY-MM-DD``
- ``YYYY-MM-DD HH:MM:SS``
.. note:: If you want to parse date/time strings with a fixed, known
format and :func:`parse_date()` isn't useful to you, consider
:func:`time.strptime()` or :meth:`datetime.datetime.strptime()`,
both of which are included in the Python standard library.
Alternatively for more complex tasks consider using the date/time
parsing module in the dateutil_ package.
Examples:
>>> from humanfriendly import parse_date
>>> parse_date('2013-06-17')
(2013, 6, 17, 0, 0, 0)
>>> parse_date('2013-06-17 02:47:42')
(2013, 6, 17, 2, 47, 42)
Here's how you convert the result to a number (`Unix time`_):
>>> from humanfriendly import parse_date
>>> from time import mktime
>>> mktime(parse_date('2013-06-17 02:47:42') + (-1, -1, -1))
1371430062.0
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 :func:`format_timespan()` and
:func:`parse_date()` to calculate a human friendly timespan since a
given date:
>>> from humanfriendly import format_timespan, parse_date
>>> from time import mktime, time
>>> unix_time = mktime(parse_date('2013-06-17 02:47:42') + (-1, -1, -1))
>>> seconds_since_then = time() - unix_time
>>> print(format_timespan(seconds_since_then))
1 year, 43 weeks and 1 day
.. _dateutil: https://dateutil.readthedocs.io/en/latest/parser.html
.. _Unix time: http://en.wikipedia.org/wiki/Unix_time
"""
try:
tokens = [t.strip() for t in datestring.split()]
if len(tokens) >= 2:
date_parts = list(map(int, tokens[0].split('-'))) + [1, 1]
time_parts = list(map(int, tokens[1].split(':'))) + [0, 0, 0]
return tuple(date_parts[0:3] + time_parts[0:3])
else:
year, month, day = (list(map(int, datestring.split('-'))) + [1, 1])[0:3]
return (year, month, day, 0, 0, 0)
except Exception:
msg = "Invalid date! (expected 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS' but got: %r)"
raise InvalidDate(format(msg, datestring))
def format_path(pathname):
"""
Shorten a pathname to make it more human friendly.
:param pathname: An absolute pathname (a string).
:returns: The pathname with the user's home directory abbreviated.
Given an absolute pathname, this function abbreviates the user's home
directory to ``~/`` in order to shorten the pathname without losing
information. It is not an error if the pathname is not relative to the
current user's home directory.
Here's an example of its usage:
>>> from os import environ
>>> from os.path import join
>>> vimrc = join(environ['HOME'], '.vimrc')
>>> vimrc
'/home/peter/.vimrc'
>>> from humanfriendly import format_path
>>> format_path(vimrc)
'~/.vimrc'
"""
pathname = os.path.abspath(pathname)
home = os.environ.get('HOME')
if home:
home = os.path.abspath(home)
if pathname.startswith(home):
pathname = os.path.join('~', os.path.relpath(pathname, home))
return pathname
def parse_path(pathname):
"""
Convert a human friendly pathname to an absolute pathname.
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).
"""
return os.path.abspath(os.path.expanduser(os.path.expandvars(pathname)))
class Timer(object):
"""
Easy to use timer to keep track of long during operations.
"""
def __init__(self, start_time=None, resumable=False):
"""
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`).
When `start_time` is given :class:`Timer` uses :func:`time.time()` as a
clock source, otherwise it uses :func:`humanfriendly.compat.monotonic()`.
"""
if resumable:
self.monotonic = True
self.resumable = True
self.start_time = 0.0
self.total_time = 0.0
elif start_time:
self.monotonic = False
self.resumable = False
self.start_time = start_time
else:
self.monotonic = True
self.resumable = False
self.start_time = monotonic()
def __enter__(self):
"""
Start or resume counting elapsed time.
:returns: The :class:`Timer` object.
:raises: :exc:`~exceptions.ValueError` when the timer isn't resumable.
"""
if not self.resumable:
raise ValueError("Timer is not resumable!")
self.start_time = monotonic()
return self
def __exit__(self, exc_type=None, exc_value=None, traceback=None):
"""
Stop counting elapsed time.
:raises: :exc:`~exceptions.ValueError` when the timer isn't resumable.
"""
if not self.resumable:
raise ValueError("Timer is not resumable!")
if self.start_time:
self.total_time += monotonic() - self.start_time
self.start_time = 0.0
def sleep(self, seconds):
"""
Easy to use rate limiting of repeating actions.
:param seconds: The number of seconds to sleep (an
integer or floating point number).
This method sleeps for the given number of seconds minus the
:attr:`elapsed_time`. If the resulting duration is negative
:func:`time.sleep()` will still be called, but the argument
given to it will be the number 0 (negative numbers cause
:func:`time.sleep()` to raise an exception).
The use case for this is to initialize a :class:`Timer` inside
the body of a :keyword:`for` or :keyword:`while` loop and call
:func:`Timer.sleep()` at the end of the loop body to rate limit
whatever it is that is being done inside the loop body.
For posterity: Although the implementation of :func:`sleep()` only
requires a single line of code I've added it to :mod:`humanfriendly`
anyway because now that I've thought about how to tackle this once I
never want to have to think about it again :-P (unless I find ways to
improve this).
"""
time.sleep(max(0, seconds - self.elapsed_time))
@property
def elapsed_time(self):
"""
Get the number of seconds counted so far.
"""
elapsed_time = 0
if self.resumable:
elapsed_time += self.total_time
if self.start_time:
current_time = monotonic() if self.monotonic else time.time()
elapsed_time += current_time - self.start_time
return elapsed_time
@property
def rounded(self):
"""Human readable timespan rounded to seconds (a string)."""
return format_timespan(round(self.elapsed_time))
def __str__(self):
"""Show the elapsed time since the :class:`Timer` was created."""
return format_timespan(self.elapsed_time)
class InvalidDate(Exception):
"""
Raised when a string cannot be parsed into a date.
For example:
>>> from humanfriendly import parse_date
>>> parse_date('2013-06-XY')
Traceback (most recent call last):
File "humanfriendly.py", line 206, in parse_date
raise InvalidDate(format(msg, datestring))
humanfriendly.InvalidDate: Invalid date! (expected 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS' but got: '2013-06-XY')
"""
class InvalidSize(Exception):
"""
Raised when a string cannot be parsed into a file size.
For example:
>>> from humanfriendly import parse_size
>>> parse_size('5 Z')
Traceback (most recent call last):
File "humanfriendly/__init__.py", line 267, in parse_size
raise InvalidSize(format(msg, size, tokens))
humanfriendly.InvalidSize: Failed to parse size! (input '5 Z' was tokenized as [5, 'Z'])
"""
class InvalidLength(Exception):
"""
Raised when a string cannot be parsed into a length.
For example:
>>> from humanfriendly import parse_length
>>> parse_length('5 Z')
Traceback (most recent call last):
File "humanfriendly/__init__.py", line 267, in parse_length
raise InvalidLength(format(msg, length, tokens))
humanfriendly.InvalidLength: Failed to parse length! (input '5 Z' was tokenized as [5, 'Z'])
"""
class InvalidTimespan(Exception):
"""
Raised when a string cannot be parsed into a timespan.
For example:
>>> from humanfriendly import parse_timespan
>>> parse_timespan('1 age')
Traceback (most recent call last):
File "humanfriendly/__init__.py", line 419, in parse_timespan
raise InvalidTimespan(format(msg, timespan, tokens))
humanfriendly.InvalidTimespan: Failed to parse timespan! (input '1 age' was tokenized as [1, 'age'])
"""
# Define aliases for backwards compatibility.
define_aliases(
module_name=__name__,
# In humanfriendly 1.23 the format_table() function was added to render a
# table using characters like dashes and vertical bars to emulate borders.
# Since then support for other tables has been added and the name of
# format_table() has changed.
format_table='humanfriendly.tables.format_pretty_table',
# In humanfriendly 1.30 the following text manipulation functions were
# moved out into a separate module to enable their usage in other modules
# of the humanfriendly package (without causing circular imports).
compact='humanfriendly.text.compact',
concatenate='humanfriendly.text.concatenate',
dedent='humanfriendly.text.dedent',
format='humanfriendly.text.format',
is_empty_line='humanfriendly.text.is_empty_line',
pluralize='humanfriendly.text.pluralize',
tokenize='humanfriendly.text.tokenize',
trim_empty_lines='humanfriendly.text.trim_empty_lines',
# In humanfriendly 1.38 the prompt_for_choice() function was moved out into a
# separate module because several variants of interactive prompts were added.
prompt_for_choice='humanfriendly.prompts.prompt_for_choice',
# In humanfriendly 8.0 the Spinner class and minimum_spinner_interval
# variable were extracted to a new module and the erase_line_code,
# hide_cursor_code and show_cursor_code variables were moved.
AutomaticSpinner='humanfriendly.terminal.spinners.AutomaticSpinner',
Spinner='humanfriendly.terminal.spinners.Spinner',
erase_line_code='humanfriendly.terminal.ANSI_ERASE_LINE',
hide_cursor_code='humanfriendly.terminal.ANSI_SHOW_CURSOR',
minimum_spinner_interval='humanfriendly.terminal.spinners.MINIMUM_INTERVAL',
show_cursor_code='humanfriendly.terminal.ANSI_HIDE_CURSOR',
)

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/__init__.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/case.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/cli.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/compat.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/decorators.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/deprecation.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/prompts.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/sphinx.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/tables.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/testing.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/tests.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/text.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/__pycache__/usage.cpython-312.pyc Normal file
View File

Binary file not shown.

157
venv/lib/python3.12/site-packages/humanfriendly/case.py Normal file
View File

@@ -0,0 +1,157 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: April 19, 2020
# URL: https://humanfriendly.readthedocs.io
"""
Simple case insensitive dictionaries.
The :class:`CaseInsensitiveDict` class is a dictionary whose string keys
are case insensitive. It works by automatically coercing string keys to
:class:`CaseInsensitiveKey` objects. Keys that are not strings are
supported as well, just without case insensitivity.
At its core this module works by normalizing strings to lowercase before
comparing or hashing them. It doesn't support proper case folding nor
does it support Unicode normalization, hence the word "simple".
"""
# Standard library modules.
import collections
try:
# Python >= 3.3.
from collections.abc import Iterable, Mapping
except ImportError:
# Python 2.7.
from collections import Iterable, Mapping
# Modules included in our package.
from humanfriendly.compat import basestring, unicode
# Public identifiers that require documentation.
__all__ = ("CaseInsensitiveDict", "CaseInsensitiveKey")
class CaseInsensitiveDict(collections.OrderedDict):
"""
Simple case insensitive dictionary implementation (that remembers insertion order).
This class works by overriding methods that deal with dictionary keys to
coerce string keys to :class:`CaseInsensitiveKey` objects before calling
down to the regular dictionary handling methods. While intended to be
complete this class has not been extensively tested yet.
"""
def __init__(self, other=None, **kw):
"""Initialize a :class:`CaseInsensitiveDict` object."""
# Initialize our superclass.
super(CaseInsensitiveDict, self).__init__()
# Handle the initializer arguments.
self.update(other, **kw)
def coerce_key(self, key):
"""
Coerce string keys to :class:`CaseInsensitiveKey` objects.
:param key: The value to coerce (any type).
:returns: If `key` is a string then a :class:`CaseInsensitiveKey`
object is returned, otherwise the value of `key` is
returned unmodified.
"""
if isinstance(key, basestring):
key = CaseInsensitiveKey(key)
return key
@classmethod
def fromkeys(cls, iterable, value=None):
"""Create a case insensitive dictionary with keys from `iterable` and values set to `value`."""
return cls((k, value) for k in iterable)
def get(self, key, default=None):
"""Get the value of an existing item."""
return super(CaseInsensitiveDict, self).get(self.coerce_key(key), default)
def pop(self, key, default=None):
"""Remove an item from a case insensitive dictionary."""
return super(CaseInsensitiveDict, self).pop(self.coerce_key(key), default)
def setdefault(self, key, default=None):
"""Get the value of an existing item or add a new item."""
return super(CaseInsensitiveDict, self).setdefault(self.coerce_key(key), default)
def update(self, other=None, **kw):
"""Update a case insensitive dictionary with new items."""
if isinstance(other, Mapping):
# Copy the items from the given mapping.
for key, value in other.items():
self[key] = value
elif isinstance(other, Iterable):
# Copy the items from the given iterable.
for key, value in other:
self[key] = value
elif other is not None:
# Complain about unsupported values.
msg = "'%s' object is not iterable"
type_name = type(value).__name__
raise TypeError(msg % type_name)
# Copy the keyword arguments (if any).
for key, value in kw.items():
self[key] = value
def __contains__(self, key):
"""Check if a case insensitive dictionary contains the given key."""
return super(CaseInsensitiveDict, self).__contains__(self.coerce_key(key))
def __delitem__(self, key):
"""Delete an item in a case insensitive dictionary."""
return super(CaseInsensitiveDict, self).__delitem__(self.coerce_key(key))
def __getitem__(self, key):
"""Get the value of an item in a case insensitive dictionary."""
return super(CaseInsensitiveDict, self).__getitem__(self.coerce_key(key))
def __setitem__(self, key, value):
"""Set the value of an item in a case insensitive dictionary."""
return super(CaseInsensitiveDict, self).__setitem__(self.coerce_key(key), value)
class CaseInsensitiveKey(unicode):
"""
Simple case insensitive dictionary key implementation.
The :class:`CaseInsensitiveKey` class provides an intentionally simple
implementation of case insensitive strings to be used as dictionary keys.
If you need features like Unicode normalization or proper case folding
please consider using a more advanced implementation like the :pypi:`istr`
package instead.
"""
def __new__(cls, value):
"""Create a :class:`CaseInsensitiveKey` object."""
# Delegate string object creation to our superclass.
obj = unicode.__new__(cls, value)
# Store the lowercased string and its hash value.
normalized = obj.lower()
obj._normalized = normalized
obj._hash_value = hash(normalized)
return obj
def __hash__(self):
"""Get the hash value of the lowercased string."""
return self._hash_value
def __eq__(self, other):
"""Compare two strings as lowercase."""
if isinstance(other, CaseInsensitiveKey):
# Fast path (and the most common case): Comparison with same type.
return self._normalized == other._normalized
elif isinstance(other, unicode):
# Slow path: Comparison with strings that need lowercasing.
return self._normalized == other.lower()
else:
return NotImplemented

291
venv/lib/python3.12/site-packages/humanfriendly/cli.py Normal file
View File

@@ -0,0 +1,291 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: March 1, 2020
# URL: https://humanfriendly.readthedocs.io
"""
Usage: humanfriendly [OPTIONS]
Human friendly input/output (text formatting) on the command
line based on the Python package with the same name.
Supported options:
-c, --run-command
Execute an external command (given as the positional arguments) and render
a spinner and timer while the command is running. The exit status of the
command is propagated.
--format-table
Read tabular data from standard input (each line is a row and each
whitespace separated field is a column), format the data as a table and
print the resulting table to standard output. See also the --delimiter
option.
-d, --delimiter=VALUE
Change the delimiter used by --format-table to VALUE (a string). By default
all whitespace is treated as a delimiter.
-l, --format-length=LENGTH
Convert a length count (given as the integer or float LENGTH) into a human
readable string and print that string to standard output.
-n, --format-number=VALUE
Format a number (given as the integer or floating point number VALUE) with
thousands separators and two decimal places (if needed) and print the
formatted number to standard output.
-s, --format-size=BYTES
Convert a byte count (given as the integer BYTES) into a human readable
string and print that string to standard output.
-b, --binary
Change the output of -s, --format-size to use binary multiples of bytes
(base-2) instead of the default decimal multiples of bytes (base-10).
-t, --format-timespan=SECONDS
Convert a number of seconds (given as the floating point number SECONDS)
into a human readable timespan and print that string to standard output.
--parse-length=VALUE
Parse a human readable length (given as the string VALUE) and print the
number of metres to standard output.
--parse-size=VALUE
Parse a human readable data size (given as the string VALUE) and print the
number of bytes to standard output.
--demo
Demonstrate changing the style and color of the terminal font using ANSI
escape sequences.
-h, --help
Show this message and exit.
"""
# Standard library modules.
import functools
import getopt
import pipes
import subprocess
import sys
# Modules included in our package.
from humanfriendly import (
Timer,
format_length,
format_number,
format_size,
format_timespan,
parse_length,
parse_size,
)
from humanfriendly.tables import format_pretty_table, format_smart_table
from humanfriendly.terminal import (
ANSI_COLOR_CODES,
ANSI_TEXT_STYLES,
HIGHLIGHT_COLOR,
ansi_strip,
ansi_wrap,
enable_ansi_support,
find_terminal_size,
output,
usage,
warning,
)
from humanfriendly.terminal.spinners import Spinner
# Public identifiers that require documentation.
__all__ = (
'demonstrate_256_colors',
'demonstrate_ansi_formatting',
'main',
'print_formatted_length',
'print_formatted_number',
'print_formatted_size',
'print_formatted_table',
'print_formatted_timespan',
'print_parsed_length',
'print_parsed_size',
'run_command',
)
def main():
"""Command line interface for the ``humanfriendly`` program."""
enable_ansi_support()
try:
options, arguments = getopt.getopt(sys.argv[1:], 'cd:l:n:s:bt:h', [
'run-command', 'format-table', 'delimiter=', 'format-length=',
'format-number=', 'format-size=', 'binary', 'format-timespan=',
'parse-length=', 'parse-size=', 'demo', 'help',
])
except Exception as e:
warning("Error: %s", e)
sys.exit(1)
actions = []
delimiter = None
should_format_table = False
binary = any(o in ('-b', '--binary') for o, v in options)
for option, value in options:
if option in ('-d', '--delimiter'):
delimiter = value
elif option == '--parse-size':
actions.append(functools.partial(print_parsed_size, value))
elif option == '--parse-length':
actions.append(functools.partial(print_parsed_length, value))
elif option in ('-c', '--run-command'):
actions.append(functools.partial(run_command, arguments))
elif option in ('-l', '--format-length'):
actions.append(functools.partial(print_formatted_length, value))
elif option in ('-n', '--format-number'):
actions.append(functools.partial(print_formatted_number, value))
elif option in ('-s', '--format-size'):
actions.append(functools.partial(print_formatted_size, value, binary))
elif option == '--format-table':
should_format_table = True
elif option in ('-t', '--format-timespan'):
actions.append(functools.partial(print_formatted_timespan, value))
elif option == '--demo':
actions.append(demonstrate_ansi_formatting)
elif option in ('-h', '--help'):
usage(__doc__)
return
if should_format_table:
actions.append(functools.partial(print_formatted_table, delimiter))
if not actions:
usage(__doc__)
return
for partial in actions:
partial()
def run_command(command_line):
"""Run an external command and show a spinner while the command is running."""
timer = Timer()
spinner_label = "Waiting for command: %s" % " ".join(map(pipes.quote, command_line))
with Spinner(label=spinner_label, timer=timer) as spinner:
process = subprocess.Popen(command_line)
while True:
spinner.step()
spinner.sleep()
if process.poll() is not None:
break
sys.exit(process.returncode)
def print_formatted_length(value):
"""Print a human readable length."""
if '.' in value:
output(format_length(float(value)))
else:
output(format_length(int(value)))
def print_formatted_number(value):
"""Print large numbers in a human readable format."""
output(format_number(float(value)))
def print_formatted_size(value, binary):
"""Print a human readable size."""
output(format_size(int(value), binary=binary))
def print_formatted_table(delimiter):
"""Read tabular data from standard input and print a table."""
data = []
for line in sys.stdin:
line = line.rstrip()
data.append(line.split(delimiter))
output(format_pretty_table(data))
def print_formatted_timespan(value):
"""Print a human readable timespan."""
output(format_timespan(float(value)))
def print_parsed_length(value):
"""Parse a human readable length and print the number of metres."""
output(parse_length(value))
def print_parsed_size(value):
"""Parse a human readable data size and print the number of bytes."""
output(parse_size(value))
def demonstrate_ansi_formatting():
"""Demonstrate the use of ANSI escape sequences."""
# First we demonstrate the supported text styles.
output('%s', ansi_wrap('Text styles:', bold=True))
styles = ['normal', 'bright']
styles.extend(ANSI_TEXT_STYLES.keys())
for style_name in sorted(styles):
options = dict(color=HIGHLIGHT_COLOR)
if style_name != 'normal':
options[style_name] = True
style_label = style_name.replace('_', ' ').capitalize()
output(' - %s', ansi_wrap(style_label, **options))
# Now we demonstrate named foreground and background colors.
for color_type, color_label in (('color', 'Foreground colors'),
('background', 'Background colors')):
intensities = [
('normal', dict()),
('bright', dict(bright=True)),
]
if color_type != 'background':
intensities.insert(0, ('faint', dict(faint=True)))
output('\n%s' % ansi_wrap('%s:' % color_label, bold=True))
output(format_smart_table([
[color_name] + [
ansi_wrap(
'XXXXXX' if color_type != 'background' else (' ' * 6),
**dict(list(kw.items()) + [(color_type, color_name)])
) for label, kw in intensities
] for color_name in sorted(ANSI_COLOR_CODES.keys())
], column_names=['Color'] + [
label.capitalize() for label, kw in intensities
]))
# Demonstrate support for 256 colors as well.
demonstrate_256_colors(0, 7, 'standard colors')
demonstrate_256_colors(8, 15, 'high-intensity colors')
demonstrate_256_colors(16, 231, '216 colors')
demonstrate_256_colors(232, 255, 'gray scale colors')
def demonstrate_256_colors(i, j, group=None):
"""Demonstrate 256 color mode support."""
# Generate the label.
label = '256 color mode'
if group:
label += ' (%s)' % group
output('\n' + ansi_wrap('%s:' % label, bold=True))
# Generate a simple rendering of the colors in the requested range and
# check if it will fit on a single line (given the terminal's width).
single_line = ''.join(' ' + ansi_wrap(str(n), color=n) for n in range(i, j + 1))
lines, columns = find_terminal_size()
if columns >= len(ansi_strip(single_line)):
output(single_line)
else:
# Generate a more complex rendering of the colors that will nicely wrap
# over multiple lines without using too many lines.
width = len(str(j)) + 1
colors_per_line = int(columns / width)
colors = [ansi_wrap(str(n).rjust(width), color=n) for n in range(i, j + 1)]
blocks = [colors[n:n + colors_per_line] for n in range(0, len(colors), colors_per_line)]
output('\n'.join(''.join(b) for b in blocks))

146
venv/lib/python3.12/site-packages/humanfriendly/compat.py Normal file
View File

@@ -0,0 +1,146 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: September 17, 2021
# URL: https://humanfriendly.readthedocs.io
"""
Compatibility with Python 2 and 3.
This module exposes aliases and functions that make it easier to write Python
code that is compatible with Python 2 and Python 3.
.. data:: basestring
Alias for :func:`python2:basestring` (in Python 2) or :class:`python3:str`
(in Python 3). See also :func:`is_string()`.
.. data:: HTMLParser
Alias for :class:`python2:HTMLParser.HTMLParser` (in Python 2) or
:class:`python3:html.parser.HTMLParser` (in Python 3).
.. data:: interactive_prompt
Alias for :func:`python2:raw_input()` (in Python 2) or
:func:`python3:input()` (in Python 3).
.. data:: StringIO
Alias for :class:`python2:StringIO.StringIO` (in Python 2) or
:class:`python3:io.StringIO` (in Python 3).
.. data:: unicode
Alias for :func:`python2:unicode` (in Python 2) or :class:`python3:str` (in
Python 3). See also :func:`coerce_string()`.
.. data:: monotonic
Alias for :func:`python3:time.monotonic()` (in Python 3.3 and higher) or
`monotonic.monotonic()` (a `conditional dependency
<https://pypi.org/project/monotonic/>`_ on older Python versions).
"""
__all__ = (
'HTMLParser',
'StringIO',
'basestring',
'coerce_string',
'interactive_prompt',
'is_string',
'is_unicode',
'monotonic',
'name2codepoint',
'on_macos',
'on_windows',
'unichr',
'unicode',
'which',
)
# Standard library modules.
import sys
# Differences between Python 2 and 3.
try:
# Python 2.
unicode = unicode
unichr = unichr
basestring = basestring
interactive_prompt = raw_input
from distutils.spawn import find_executable as which
from HTMLParser import HTMLParser
from StringIO import StringIO
from htmlentitydefs import name2codepoint
except (ImportError, NameError):
# Python 3.
unicode = str
unichr = chr
basestring = str
interactive_prompt = input
from shutil import which
from html.parser import HTMLParser
from io import StringIO
from html.entities import name2codepoint
try:
# Python 3.3 and higher.
from time import monotonic
except ImportError:
# A replacement for older Python versions:
# https://pypi.org/project/monotonic/
try:
from monotonic import monotonic
except (ImportError, RuntimeError):
# We fall back to the old behavior of using time.time() instead of
# failing when {time,monotonic}.monotonic() are both missing.
from time import time as monotonic
def coerce_string(value):
"""
Coerce any value to a Unicode string (:func:`python2:unicode` in Python 2 and :class:`python3:str` in Python 3).
:param value: The value to coerce.
:returns: The value coerced to a Unicode string.
"""
return value if is_string(value) else unicode(value)
def is_string(value):
"""
Check if a value is a :func:`python2:basestring` (in Python 2) or :class:`python3:str` (in Python 3) object.
:param value: The value to check.
:returns: :data:`True` if the value is a string, :data:`False` otherwise.
"""
return isinstance(value, basestring)
def is_unicode(value):
"""
Check if a value is a :func:`python2:unicode` (in Python 2) or :class:`python2:str` (in Python 3) object.
:param value: The value to check.
:returns: :data:`True` if the value is a Unicode string, :data:`False` otherwise.
"""
return isinstance(value, unicode)
def on_macos():
"""
Check if we're running on Apple MacOS.
:returns: :data:`True` if running MacOS, :data:`False` otherwise.
"""
return sys.platform.startswith('darwin')
def on_windows():
"""
Check if we're running on the Microsoft Windows OS.
:returns: :data:`True` if running Windows, :data:`False` otherwise.
"""
return sys.platform.startswith('win')

43
venv/lib/python3.12/site-packages/humanfriendly/decorators.py Normal file
View File

@@ -0,0 +1,43 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: March 2, 2020
# URL: https://humanfriendly.readthedocs.io
"""Simple function decorators to make Python programming easier."""
# Standard library modules.
import functools
# Public identifiers that require documentation.
__all__ = ('RESULTS_ATTRIBUTE', 'cached')
RESULTS_ATTRIBUTE = 'cached_results'
"""The name of the property used to cache the return values of functions (a string)."""
def cached(function):
"""
Rudimentary caching decorator for functions.
:param function: The function whose return value should be cached.
:returns: The decorated function.
The given function will only be called once, the first time the wrapper
function is called. The return value is cached by the wrapper function as
an attribute of the given function and returned on each subsequent call.
.. note:: Currently no function arguments are supported because only a
single return value can be cached. Accepting any function
arguments at all would imply that the cache is parametrized on
function arguments, which is not currently the case.
"""
@functools.wraps(function)
def wrapper():
try:
return getattr(wrapper, RESULTS_ATTRIBUTE)
except AttributeError:
result = function()
setattr(wrapper, RESULTS_ATTRIBUTE, result)
return result
return wrapper

251
venv/lib/python3.12/site-packages/humanfriendly/deprecation.py Normal file
View File

@@ -0,0 +1,251 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: March 2, 2020
# URL: https://humanfriendly.readthedocs.io
"""
Support for deprecation warnings when importing names from old locations.
When software evolves, things tend to move around. This is usually detrimental
to backwards compatibility (in Python this primarily manifests itself as
:exc:`~exceptions.ImportError` exceptions).
While backwards compatibility is very important, it should not get in the way
of progress. It would be great to have the agility to move things around
without breaking backwards compatibility.
This is where the :mod:`humanfriendly.deprecation` module comes in: It enables
the definition of backwards compatible aliases that emit a deprecation warning
when they are accessed.
The way it works is that it wraps the original module in an :class:`DeprecationProxy`
object that defines a :func:`~DeprecationProxy.__getattr__()` special method to
override attribute access of the module.
"""
# Standard library modules.
import collections
import functools
import importlib
import inspect
import sys
import types
import warnings
# Modules included in our package.
from humanfriendly.text import format
# Registry of known aliases (used by humanfriendly.sphinx).
REGISTRY = collections.defaultdict(dict)
# Public identifiers that require documentation.
__all__ = ("DeprecationProxy", "define_aliases", "deprecated_args", "get_aliases", "is_method")
def define_aliases(module_name, **aliases):
"""
Update a module with backwards compatible aliases.
:param module_name: The ``__name__`` of the module (a string).
:param aliases: Each keyword argument defines an alias. The values
are expected to be "dotted paths" (strings).
The behavior of this function depends on whether the Sphinx documentation
generator is active, because the use of :class:`DeprecationProxy` to shadow the
real module in :data:`sys.modules` has the unintended side effect of
breaking autodoc support for ``:data:`` members (module variables).
To avoid breaking Sphinx the proxy object is omitted and instead the
aliased names are injected into the original module namespace, to make sure
that imports can be satisfied when the documentation is being rendered.
If you run into cyclic dependencies caused by :func:`define_aliases()` when
running Sphinx, you can try moving the call to :func:`define_aliases()` to
the bottom of the Python module you're working on.
"""
module = sys.modules[module_name]
proxy = DeprecationProxy(module, aliases)
# Populate the registry of aliases.
for name, target in aliases.items():
REGISTRY[module.__name__][name] = target
# Avoid confusing Sphinx.
if "sphinx" in sys.modules:
for name, target in aliases.items():
setattr(module, name, proxy.resolve(target))
else:
# Install a proxy object to raise DeprecationWarning.
sys.modules[module_name] = proxy
def get_aliases(module_name):
"""
Get the aliases defined by a module.
:param module_name: The ``__name__`` of the module (a string).
:returns: A dictionary with string keys and values:
1. Each key gives the name of an alias
created for backwards compatibility.
2. Each value gives the dotted path of
the proper location of the identifier.
An empty dictionary is returned for modules that
don't define any backwards compatible aliases.
"""
return REGISTRY.get(module_name, {})
def deprecated_args(*names):
"""
Deprecate positional arguments without dropping backwards compatibility.
:param names:
The positional arguments to :func:`deprecated_args()` give the names of
the positional arguments that the to-be-decorated function should warn
about being deprecated and translate to keyword arguments.
:returns: A decorator function specialized to `names`.
The :func:`deprecated_args()` decorator function was created to make it
easy to switch from positional arguments to keyword arguments [#]_ while
preserving backwards compatibility [#]_ and informing call sites
about the change.
.. [#] Increased flexibility is the main reason why I find myself switching
from positional arguments to (optional) keyword arguments as my code
evolves to support more use cases.
.. [#] In my experience positional argument order implicitly becomes part
of API compatibility whether intended or not. While this makes sense
for functions that over time adopt more and more optional arguments,
at a certain point it becomes an inconvenience to code maintenance.
Here's an example of how to use the decorator::
@deprecated_args('text')
def report_choice(**options):
print(options['text'])
When the decorated function is called with positional arguments
a deprecation warning is given::
>>> report_choice('this will give a deprecation warning')
DeprecationWarning: report_choice has deprecated positional arguments, please switch to keyword arguments
this will give a deprecation warning
But when the function is called with keyword arguments no deprecation
warning is emitted::
>>> report_choice(text='this will not give a deprecation warning')
this will not give a deprecation warning
"""
def decorator(function):
def translate(args, kw):
# Raise TypeError when too many positional arguments are passed to the decorated function.
if len(args) > len(names):
raise TypeError(
format(
"{name} expected at most {limit} arguments, got {count}",
name=function.__name__,
limit=len(names),
count=len(args),
)
)
# Emit a deprecation warning when positional arguments are used.
if args:
warnings.warn(
format(
"{name} has deprecated positional arguments, please switch to keyword arguments",
name=function.__name__,
),
category=DeprecationWarning,
stacklevel=3,
)
# Translate positional arguments to keyword arguments.
for name, value in zip(names, args):
kw[name] = value
if is_method(function):
@functools.wraps(function)
def wrapper(*args, **kw):
"""Wrapper for instance methods."""
args = list(args)
self = args.pop(0)
translate(args, kw)
return function(self, **kw)
else:
@functools.wraps(function)
def wrapper(*args, **kw):
"""Wrapper for module level functions."""
translate(args, kw)
return function(**kw)
return wrapper
return decorator
def is_method(function):
"""Check if the expected usage of the given function is as an instance method."""
try:
# Python 3.3 and newer.
signature = inspect.signature(function)
return "self" in signature.parameters
except AttributeError:
# Python 3.2 and older.
metadata = inspect.getargspec(function)
return "self" in metadata.args
class DeprecationProxy(types.ModuleType):
"""Emit deprecation warnings for imports that should be updated."""
def __init__(self, module, aliases):
"""
Initialize an :class:`DeprecationProxy` object.
:param module: The original module object.
:param aliases: A dictionary of aliases.
"""
# Initialize our superclass.
super(DeprecationProxy, self).__init__(name=module.__name__)
# Store initializer arguments.
self.module = module
self.aliases = aliases
def __getattr__(self, name):
"""
Override module attribute lookup.
:param name: The name to look up (a string).
:returns: The attribute value.
"""
# Check if the given name is an alias.
target = self.aliases.get(name)
if target is not None:
# Emit the deprecation warning.
warnings.warn(
format("%s.%s was moved to %s, please update your imports", self.module.__name__, name, target),
category=DeprecationWarning,
stacklevel=2,
)
# Resolve the dotted path.
return self.resolve(target)
# Look up the name in the original module namespace.
value = getattr(self.module, name, None)
if value is not None:
return value
# Fall back to the default behavior.
raise AttributeError(format("module '%s' has no attribute '%s'", self.module.__name__, name))
def resolve(self, target):
"""
Look up the target of an alias.
:param target: The fully qualified dotted path (a string).
:returns: The value of the given target.
"""
module_name, _, member = target.rpartition(".")
module = importlib.import_module(module_name)
return getattr(module, member)

376
venv/lib/python3.12/site-packages/humanfriendly/prompts.py Normal file
View File

@@ -0,0 +1,376 @@
# vim: fileencoding=utf-8
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: February 9, 2020
# URL: https://humanfriendly.readthedocs.io
"""
Interactive terminal prompts.
The :mod:`~humanfriendly.prompts` module enables interaction with the user
(operator) by asking for confirmation (:func:`prompt_for_confirmation()`) and
asking to choose from a list of options (:func:`prompt_for_choice()`). It works
by rendering interactive prompts on the terminal.
"""
# Standard library modules.
import logging
import sys
# Modules included in our package.
from humanfriendly.compat import interactive_prompt
from humanfriendly.terminal import (
HIGHLIGHT_COLOR,
ansi_strip,
ansi_wrap,
connected_to_terminal,
terminal_supports_colors,
warning,
)
from humanfriendly.text import format, concatenate
# Public identifiers that require documentation.
__all__ = (
'MAX_ATTEMPTS',
'TooManyInvalidReplies',
'logger',
'prepare_friendly_prompts',
'prepare_prompt_text',
'prompt_for_choice',
'prompt_for_confirmation',
'prompt_for_input',
'retry_limit',
)
MAX_ATTEMPTS = 10
"""The number of times an interactive prompt is shown on invalid input (an integer)."""
# Initialize a logger for this module.
logger = logging.getLogger(__name__)
def prompt_for_confirmation(question, default=None, padding=True):
"""
Prompt the user for confirmation.
:param question: The text that explains what the user is confirming (a string).
:param default: The default value (a boolean) or :data:`None`.
:param padding: Refer to the documentation of :func:`prompt_for_input()`.
:returns: - If the user enters 'yes' or 'y' then :data:`True` is returned.
- If the user enters 'no' or 'n' then :data:`False` is returned.
- If the user doesn't enter any text or standard input is not
connected to a terminal (which makes it impossible to prompt
the user) the value of the keyword argument ``default`` is
returned (if that value is not :data:`None`).
:raises: - Any exceptions raised by :func:`retry_limit()`.
- Any exceptions raised by :func:`prompt_for_input()`.
When `default` is :data:`False` and the user doesn't enter any text an
error message is printed and the prompt is repeated:
>>> prompt_for_confirmation("Are you sure?")
<BLANKLINE>
Are you sure? [y/n]
<BLANKLINE>
Error: Please enter 'yes' or 'no' (there's no default choice).
<BLANKLINE>
Are you sure? [y/n]
The same thing happens when the user enters text that isn't recognized:
>>> prompt_for_confirmation("Are you sure?")
<BLANKLINE>
Are you sure? [y/n] about what?
<BLANKLINE>
Error: Please enter 'yes' or 'no' (the text 'about what?' is not recognized).
<BLANKLINE>
Are you sure? [y/n]
"""
# Generate the text for the prompt.
prompt_text = prepare_prompt_text(question, bold=True)
# Append the valid replies (and default reply) to the prompt text.
hint = "[Y/n]" if default else "[y/N]" if default is not None else "[y/n]"
prompt_text += " %s " % prepare_prompt_text(hint, color=HIGHLIGHT_COLOR)
# Loop until a valid response is given.
logger.debug("Requesting interactive confirmation from terminal: %r", ansi_strip(prompt_text).rstrip())
for attempt in retry_limit():
reply = prompt_for_input(prompt_text, '', padding=padding, strip=True)
if reply.lower() in ('y', 'yes'):
logger.debug("Confirmation granted by reply (%r).", reply)
return True
elif reply.lower() in ('n', 'no'):
logger.debug("Confirmation denied by reply (%r).", reply)
return False
elif (not reply) and default is not None:
logger.debug("Default choice selected by empty reply (%r).",
"granted" if default else "denied")
return default
else:
details = ("the text '%s' is not recognized" % reply
if reply else "there's no default choice")
logger.debug("Got %s reply (%s), retrying (%i/%i) ..",
"invalid" if reply else "empty", details,
attempt, MAX_ATTEMPTS)
warning("{indent}Error: Please enter 'yes' or 'no' ({details}).",
indent=' ' if padding else '', details=details)
def prompt_for_choice(choices, default=None, padding=True):
"""
Prompt the user to select a choice from a group of options.
:param choices: A sequence of strings with available options.
:param default: The default choice if the user simply presses Enter
(expected to be a string, defaults to :data:`None`).
:param padding: Refer to the documentation of
:func:`~humanfriendly.prompts.prompt_for_input()`.
:returns: The string corresponding to the user's choice.
:raises: - :exc:`~exceptions.ValueError` if `choices` is an empty sequence.
- Any exceptions raised by
:func:`~humanfriendly.prompts.retry_limit()`.
- Any exceptions raised by
:func:`~humanfriendly.prompts.prompt_for_input()`.
When no options are given an exception is raised:
>>> prompt_for_choice([])
Traceback (most recent call last):
File "humanfriendly/prompts.py", line 148, in prompt_for_choice
raise ValueError("Can't prompt for choice without any options!")
ValueError: Can't prompt for choice without any options!
If a single option is given the user isn't prompted:
>>> prompt_for_choice(['only one choice'])
'only one choice'
Here's what the actual prompt looks like by default:
>>> prompt_for_choice(['first option', 'second option'])
<BLANKLINE>
1. first option
2. second option
<BLANKLINE>
Enter your choice as a number or unique substring (Control-C aborts): second
<BLANKLINE>
'second option'
If you don't like the whitespace (empty lines and indentation):
>>> prompt_for_choice(['first option', 'second option'], padding=False)
1. first option
2. second option
Enter your choice as a number or unique substring (Control-C aborts): first
'first option'
"""
indent = ' ' if padding else ''
# Make sure we can use 'choices' more than once (i.e. not a generator).
choices = list(choices)
if len(choices) == 1:
# If there's only one option there's no point in prompting the user.
logger.debug("Skipping interactive prompt because there's only option (%r).", choices[0])
return choices[0]
elif not choices:
# We can't render a choice prompt without any options.
raise ValueError("Can't prompt for choice without any options!")
# Generate the prompt text.
prompt_text = ('\n\n' if padding else '\n').join([
# Present the available choices in a user friendly way.
"\n".join([
(u" %i. %s" % (i, choice)) + (" (default choice)" if choice == default else "")
for i, choice in enumerate(choices, start=1)
]),
# Instructions for the user.
"Enter your choice as a number or unique substring (Control-C aborts): ",
])
prompt_text = prepare_prompt_text(prompt_text, bold=True)
# Loop until a valid choice is made.
logger.debug("Requesting interactive choice on terminal (options are %s) ..",
concatenate(map(repr, choices)))
for attempt in retry_limit():
reply = prompt_for_input(prompt_text, '', padding=padding, strip=True)
if not reply and default is not None:
logger.debug("Default choice selected by empty reply (%r).", default)
return default
elif reply.isdigit():
index = int(reply) - 1
if 0 <= index < len(choices):
logger.debug("Option (%r) selected by numeric reply (%s).", choices[index], reply)
return choices[index]
# Check for substring matches.
matches = []
for choice in choices:
lower_reply = reply.lower()
lower_choice = choice.lower()
if lower_reply == lower_choice:
# If we have an 'exact' match we return it immediately.
logger.debug("Option (%r) selected by reply (exact match).", choice)
return choice
elif lower_reply in lower_choice and len(lower_reply) > 0:
# Otherwise we gather substring matches.
matches.append(choice)
if len(matches) == 1:
# If a single choice was matched we return it.
logger.debug("Option (%r) selected by reply (substring match on %r).", matches[0], reply)
return matches[0]
else:
# Give the user a hint about what went wrong.
if matches:
details = format("text '%s' matches more than one choice: %s", reply, concatenate(matches))
elif reply.isdigit():
details = format("number %i is not a valid choice", int(reply))
elif reply and not reply.isspace():
details = format("text '%s' doesn't match any choices", reply)
else:
details = "there's no default choice"
logger.debug("Got %s reply (%s), retrying (%i/%i) ..",
"invalid" if reply else "empty", details,
attempt, MAX_ATTEMPTS)
warning("%sError: Invalid input (%s).", indent, details)
def prompt_for_input(question, default=None, padding=True, strip=True):
"""
Prompt the user for input (free form text).
:param question: An explanation of what is expected from the user (a string).
:param default: The return value if the user doesn't enter any text or
standard input is not connected to a terminal (which
makes it impossible to prompt the user).
:param padding: Render empty lines before and after the prompt to make it
stand out from the surrounding text? (a boolean, defaults
to :data:`True`)
:param strip: Strip leading/trailing whitespace from the user's reply?
:returns: The text entered by the user (a string) or the value of the
`default` argument.
:raises: - :exc:`~exceptions.KeyboardInterrupt` when the program is
interrupted_ while the prompt is active, for example
because the user presses Control-C_.
- :exc:`~exceptions.EOFError` when reading from `standard input`_
fails, for example because the user presses Control-D_ or
because the standard input stream is redirected (only if
`default` is :data:`None`).
.. _Control-C: https://en.wikipedia.org/wiki/Control-C#In_command-line_environments
.. _Control-D: https://en.wikipedia.org/wiki/End-of-transmission_character#Meaning_in_Unix
.. _interrupted: https://en.wikipedia.org/wiki/Unix_signal#SIGINT
.. _standard input: https://en.wikipedia.org/wiki/Standard_streams#Standard_input_.28stdin.29
"""
prepare_friendly_prompts()
reply = None
try:
# Prefix an empty line to the text and indent by one space?
if padding:
question = '\n' + question
question = question.replace('\n', '\n ')
# Render the prompt and wait for the user's reply.
try:
reply = interactive_prompt(question)
finally:
if reply is None:
# If the user terminated the prompt using Control-C or
# Control-D instead of pressing Enter no newline will be
# rendered after the prompt's text. The result looks kind of
# weird:
#
# $ python -c 'print(raw_input("Are you sure? "))'
# Are you sure? ^CTraceback (most recent call last):
# File "<string>", line 1, in <module>
# KeyboardInterrupt
#
# We can avoid this by emitting a newline ourselves if an
# exception was raised (signaled by `reply' being None).
sys.stderr.write('\n')
if padding:
# If the caller requested (didn't opt out of) `padding' then we'll
# emit a newline regardless of whether an exception is being
# handled. This helps to make interactive prompts `stand out' from
# a surrounding `wall of text' on the terminal.
sys.stderr.write('\n')
except BaseException as e:
if isinstance(e, EOFError) and default is not None:
# If standard input isn't connected to an interactive terminal
# but the caller provided a default we'll return that.
logger.debug("Got EOF from terminal, returning default value (%r) ..", default)
return default
else:
# Otherwise we log that the prompt was interrupted but propagate
# the exception to the caller.
logger.warning("Interactive prompt was interrupted by exception!", exc_info=True)
raise
if default is not None and not reply:
# If the reply is empty and `default' is None we don't want to return
# None because it's nicer for callers to be able to assume that the
# return value is always a string.
return default
else:
return reply.strip()
def prepare_prompt_text(prompt_text, **options):
"""
Wrap a text to be rendered as an interactive prompt in ANSI escape sequences.
:param prompt_text: The text to render on the prompt (a string).
:param options: Any keyword arguments are passed on to :func:`.ansi_wrap()`.
:returns: The resulting prompt text (a string).
ANSI escape sequences are only used when the standard output stream is
connected to a terminal. When the standard input stream is connected to a
terminal any escape sequences are wrapped in "readline hints".
"""
return (ansi_wrap(prompt_text, readline_hints=connected_to_terminal(sys.stdin), **options)
if terminal_supports_colors(sys.stdout)
else prompt_text)
def prepare_friendly_prompts():
u"""
Make interactive prompts more user friendly.
The prompts presented by :func:`python2:raw_input()` (in Python 2) and
:func:`python3:input()` (in Python 3) are not very user friendly by
default, for example the cursor keys (:kbd:`←`, :kbd:`↑`, :kbd:`→` and
:kbd:`↓`) and the :kbd:`Home` and :kbd:`End` keys enter characters instead
of performing the action you would expect them to. By simply importing the
:mod:`readline` module these prompts become much friendlier (as mentioned
in the Python standard library documentation).
This function is called by the other functions in this module to enable
user friendly prompts.
"""
try:
import readline # NOQA
except ImportError:
# might not be available on Windows if pyreadline isn't installed
pass
def retry_limit(limit=MAX_ATTEMPTS):
"""
Allow the user to provide valid input up to `limit` times.
:param limit: The maximum number of attempts (a number,
defaults to :data:`MAX_ATTEMPTS`).
:returns: A generator of numbers starting from one.
:raises: :exc:`TooManyInvalidReplies` when an interactive prompt
receives repeated invalid input (:data:`MAX_ATTEMPTS`).
This function returns a generator for interactive prompts that want to
repeat on invalid input without getting stuck in infinite loops.
"""
for i in range(limit):
yield i + 1
msg = "Received too many invalid replies on interactive prompt, giving up! (tried %i times)"
formatted_msg = msg % limit
# Make sure the event is logged.
logger.warning(formatted_msg)
# Force the caller to decide what to do now.
raise TooManyInvalidReplies(formatted_msg)
class TooManyInvalidReplies(Exception):
"""Raised by interactive prompts when they've received too many invalid inputs."""

315
venv/lib/python3.12/site-packages/humanfriendly/sphinx.py Normal file
View File

@@ -0,0 +1,315 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: June 11, 2021
# URL: https://humanfriendly.readthedocs.io
"""
Customizations for and integration with the Sphinx_ documentation generator.
The :mod:`humanfriendly.sphinx` module uses the `Sphinx extension API`_ to
customize the process of generating Sphinx based Python documentation. To
explore the functionality this module offers its best to start reading
from the :func:`setup()` function.
.. _Sphinx: http://www.sphinx-doc.org/
.. _Sphinx extension API: http://sphinx-doc.org/extdev/appapi.html
"""
# Standard library modules.
import logging
import types
# External dependencies (if Sphinx is installed docutils will be installed).
import docutils.nodes
import docutils.utils
# Modules included in our package.
from humanfriendly.deprecation import get_aliases
from humanfriendly.text import compact, dedent, format
from humanfriendly.usage import USAGE_MARKER, render_usage
# Public identifiers that require documentation.
__all__ = (
"deprecation_note_callback",
"enable_deprecation_notes",
"enable_man_role",
"enable_pypi_role",
"enable_special_methods",
"enable_usage_formatting",
"logger",
"man_role",
"pypi_role",
"setup",
"special_methods_callback",
"usage_message_callback",
)
# Initialize a logger for this module.
logger = logging.getLogger(__name__)
def deprecation_note_callback(app, what, name, obj, options, lines):
"""
Automatically document aliases defined using :func:`~humanfriendly.deprecation.define_aliases()`.
Refer to :func:`enable_deprecation_notes()` to enable the use of this
function (you probably don't want to call :func:`deprecation_note_callback()`
directly).
This function implements a callback for ``autodoc-process-docstring`` that
reformats module docstrings to append an overview of aliases defined by the
module.
The parameters expected by this function are those defined for Sphinx event
callback functions (i.e. I'm not going to document them here :-).
"""
if isinstance(obj, types.ModuleType) and lines:
aliases = get_aliases(obj.__name__)
if aliases:
# Convert the existing docstring to a string and remove leading
# indentation from that string, otherwise our generated content
# would have to match the existing indentation in order not to
# break docstring parsing (because indentation is significant
# in the reStructuredText format).
blocks = [dedent("\n".join(lines))]
# Use an admonition to group the deprecated aliases together and
# to distinguish them from the autodoc entries that follow.
blocks.append(".. note:: Deprecated names")
indent = " " * 3
if len(aliases) == 1:
explanation = """
The following alias exists to preserve backwards compatibility,
however a :exc:`~exceptions.DeprecationWarning` is triggered
when it is accessed, because this alias will be removed
in a future release.
"""
else:
explanation = """
The following aliases exist to preserve backwards compatibility,
however a :exc:`~exceptions.DeprecationWarning` is triggered
when they are accessed, because these aliases will be
removed in a future release.
"""
blocks.append(indent + compact(explanation))
for name, target in aliases.items():
blocks.append(format("%s.. data:: %s", indent, name))
blocks.append(format("%sAlias for :obj:`%s`.", indent * 2, target))
update_lines(lines, "\n\n".join(blocks))
def enable_deprecation_notes(app):
"""
Enable documenting backwards compatibility aliases using the autodoc_ extension.
:param app: The Sphinx application object.
This function connects the :func:`deprecation_note_callback()` function to
``autodoc-process-docstring`` events.
.. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
"""
app.connect("autodoc-process-docstring", deprecation_note_callback)
def enable_man_role(app):
"""
Enable the ``:man:`` role for linking to Debian Linux manual pages.
:param app: The Sphinx application object.
This function registers the :func:`man_role()` function to handle the
``:man:`` role.
"""
app.add_role("man", man_role)
def enable_pypi_role(app):
"""
Enable the ``:pypi:`` role for linking to the Python Package Index.
:param app: The Sphinx application object.
This function registers the :func:`pypi_role()` function to handle the
``:pypi:`` role.
"""
app.add_role("pypi", pypi_role)
def enable_special_methods(app):
"""
Enable documenting "special methods" using the autodoc_ extension.
:param app: The Sphinx application object.
This function connects the :func:`special_methods_callback()` function to
``autodoc-skip-member`` events.
.. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
"""
app.connect("autodoc-skip-member", special_methods_callback)
def enable_usage_formatting(app):
"""
Reformat human friendly usage messages to reStructuredText_.
:param app: The Sphinx application object (as given to ``setup()``).
This function connects the :func:`usage_message_callback()` function to
``autodoc-process-docstring`` events.
.. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText
"""
app.connect("autodoc-process-docstring", usage_message_callback)
def man_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
"""
Convert a Linux manual topic to a hyperlink.
Using the ``:man:`` role is very simple, here's an example:
.. code-block:: rst
See the :man:`python` documentation.
This results in the following:
See the :man:`python` documentation.
As the example shows you can use the role inline, embedded in sentences of
text. In the generated documentation the ``:man:`` text is omitted and a
hyperlink pointing to the Debian Linux manual pages is emitted.
"""
man_url = "https://manpages.debian.org/%s" % text
reference = docutils.nodes.reference(rawtext, docutils.utils.unescape(text), refuri=man_url, **options)
return [reference], []
def pypi_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
"""
Generate hyperlinks to the Python Package Index.
Using the ``:pypi:`` role is very simple, here's an example:
.. code-block:: rst
See the :pypi:`humanfriendly` package.
This results in the following:
See the :pypi:`humanfriendly` package.
As the example shows you can use the role inline, embedded in sentences of
text. In the generated documentation the ``:pypi:`` text is omitted and a
hyperlink pointing to the Python Package Index is emitted.
"""
pypi_url = "https://pypi.org/project/%s/" % text
reference = docutils.nodes.reference(rawtext, docutils.utils.unescape(text), refuri=pypi_url, **options)
return [reference], []
def setup(app):
"""
Enable all of the provided Sphinx_ customizations.
:param app: The Sphinx application object.
The :func:`setup()` function makes it easy to enable all of the Sphinx
customizations provided by the :mod:`humanfriendly.sphinx` module with the
least amount of code. All you need to do is to add the module name to the
``extensions`` variable in your ``conf.py`` file:
.. code-block:: python
# Sphinx extension module names.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'humanfriendly.sphinx',
]
When Sphinx sees the :mod:`humanfriendly.sphinx` name it will import the
module and call its :func:`setup()` function. This function will then call
the following:
- :func:`enable_deprecation_notes()`
- :func:`enable_man_role()`
- :func:`enable_pypi_role()`
- :func:`enable_special_methods()`
- :func:`enable_usage_formatting()`
Of course more functionality may be added at a later stage. If you don't
like that idea you may be better of calling the individual functions from
your own ``setup()`` function.
"""
from humanfriendly import __version__
enable_deprecation_notes(app)
enable_man_role(app)
enable_pypi_role(app)
enable_special_methods(app)
enable_usage_formatting(app)
return dict(parallel_read_safe=True, parallel_write_safe=True, version=__version__)
def special_methods_callback(app, what, name, obj, skip, options):
"""
Enable documenting "special methods" using the autodoc_ extension.
Refer to :func:`enable_special_methods()` to enable the use of this
function (you probably don't want to call
:func:`special_methods_callback()` directly).
This function implements a callback for ``autodoc-skip-member`` events to
include documented "special methods" (method names with two leading and two
trailing underscores) in your documentation. The result is similar to the
use of the ``special-members`` flag with one big difference: Special
methods are included but other types of members are ignored. This means
that attributes like ``__weakref__`` will always be ignored (this was my
main annoyance with the ``special-members`` flag).
The parameters expected by this function are those defined for Sphinx event
callback functions (i.e. I'm not going to document them here :-).
"""
if getattr(obj, "__doc__", None) and isinstance(obj, (types.FunctionType, types.MethodType)):
return False
else:
return skip
def update_lines(lines, text):
"""Private helper for ``autodoc-process-docstring`` callbacks."""
while lines:
lines.pop()
lines.extend(text.splitlines())
def usage_message_callback(app, what, name, obj, options, lines):
"""
Reformat human friendly usage messages to reStructuredText_.
Refer to :func:`enable_usage_formatting()` to enable the use of this
function (you probably don't want to call :func:`usage_message_callback()`
directly).
This function implements a callback for ``autodoc-process-docstring`` that
reformats module docstrings using :func:`.render_usage()` so that Sphinx
doesn't mangle usage messages that were written to be human readable
instead of machine readable. Only module docstrings whose first line starts
with :data:`.USAGE_MARKER` are reformatted.
The parameters expected by this function are those defined for Sphinx event
callback functions (i.e. I'm not going to document them here :-).
"""
# Make sure we only modify the docstrings of modules.
if isinstance(obj, types.ModuleType) and lines:
# Make sure we only modify docstrings containing a usage message.
if lines[0].startswith(USAGE_MARKER):
# Convert the usage message to reStructuredText.
text = render_usage("\n".join(lines))
# Fill up the buffer with our modified docstring.
update_lines(lines, text)

341
venv/lib/python3.12/site-packages/humanfriendly/tables.py Normal file
View File

@@ -0,0 +1,341 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: February 16, 2020
# URL: https://humanfriendly.readthedocs.io
"""
Functions that render ASCII tables.
Some generic notes about the table formatting functions in this module:
- These functions were not written with performance in mind (*at all*) because
they're intended to format tabular data to be presented on a terminal. If
someone were to run into a performance problem using these functions, they'd
be printing so much tabular data to the terminal that a human wouldn't be
able to digest the tabular data anyway, so the point is moot :-).
- These functions ignore ANSI escape sequences (at least the ones generated by
the :mod:`~humanfriendly.terminal` module) in the calculation of columns
widths. On reason for this is that column names are highlighted in color when
connected to a terminal. It also means that you can use ANSI escape sequences
to highlight certain column's values if you feel like it (for example to
highlight deviations from the norm in an overview of calculated values).
"""
# Standard library modules.
import collections
import re
# Modules included in our package.
from humanfriendly.compat import coerce_string
from humanfriendly.terminal import (
ansi_strip,
ansi_width,
ansi_wrap,
terminal_supports_colors,
find_terminal_size,
HIGHLIGHT_COLOR,
)
# Public identifiers that require documentation.
__all__ = (
'format_pretty_table',
'format_robust_table',
'format_rst_table',
'format_smart_table',
)
# Compiled regular expression pattern to recognize table columns containing
# numeric data (integer and/or floating point numbers). Used to right-align the
# contents of such columns.
#
# Pre-emptive snarky comment: This pattern doesn't match every possible
# floating point number notation!?!1!1
#
# Response: I know, that's intentional. The use of this regular expression
# pattern has a very high DWIM level and weird floating point notations do not
# fall under the DWIM umbrella :-).
NUMERIC_DATA_PATTERN = re.compile(r'^\d+(\.\d+)?$')
def format_smart_table(data, column_names):
"""
Render tabular data using the most appropriate representation.
:param data: An iterable (e.g. a :func:`tuple` or :class:`list`)
containing the rows of the table, where each row is an
iterable containing the columns of the table (strings).
:param column_names: An iterable of column names (strings).
:returns: The rendered table (a string).
If you want an easy way to render tabular data on a terminal in a human
friendly format then this function is for you! It works as follows:
- If the input data doesn't contain any line breaks the function
:func:`format_pretty_table()` is used to render a pretty table. If the
resulting table fits in the terminal without wrapping the rendered pretty
table is returned.
- If the input data does contain line breaks or if a pretty table would
wrap (given the width of the terminal) then the function
:func:`format_robust_table()` is used to render a more robust table that
can deal with data containing line breaks and long text.
"""
# Normalize the input in case we fall back from a pretty table to a robust
# table (in which case we'll definitely iterate the input more than once).
data = [normalize_columns(r) for r in data]
column_names = normalize_columns(column_names)
# Make sure the input data doesn't contain any line breaks (because pretty
# tables break horribly when a column's text contains a line break :-).
if not any(any('\n' in c for c in r) for r in data):
# Render a pretty table.
pretty_table = format_pretty_table(data, column_names)
# Check if the pretty table fits in the terminal.
table_width = max(map(ansi_width, pretty_table.splitlines()))
num_rows, num_columns = find_terminal_size()
if table_width <= num_columns:
# The pretty table fits in the terminal without wrapping!
return pretty_table
# Fall back to a robust table when a pretty table won't work.
return format_robust_table(data, column_names)
def format_pretty_table(data, column_names=None, horizontal_bar='-', vertical_bar='|'):
"""
Render a table using characters like dashes and vertical bars to emulate borders.
:param data: An iterable (e.g. a :func:`tuple` or :class:`list`)
containing the rows of the table, where each row is an
iterable containing the columns of the table (strings).
:param column_names: An iterable of column names (strings).
:param horizontal_bar: The character used to represent a horizontal bar (a
string).
:param vertical_bar: The character used to represent a vertical bar (a
string).
:returns: The rendered table (a string).
Here's an example:
>>> from humanfriendly.tables import format_pretty_table
>>> column_names = ['Version', 'Uploaded on', 'Downloads']
>>> humanfriendly_releases = [
... ['1.23', '2015-05-25', '218'],
... ['1.23.1', '2015-05-26', '1354'],
... ['1.24', '2015-05-26', '223'],
... ['1.25', '2015-05-26', '4319'],
... ['1.25.1', '2015-06-02', '197'],
... ]
>>> print(format_pretty_table(humanfriendly_releases, column_names))
-------------------------------------
| Version | Uploaded on | Downloads |
-------------------------------------
| 1.23 | 2015-05-25 | 218 |
| 1.23.1 | 2015-05-26 | 1354 |
| 1.24 | 2015-05-26 | 223 |
| 1.25 | 2015-05-26 | 4319 |
| 1.25.1 | 2015-06-02 | 197 |
-------------------------------------
Notes about the resulting table:
- If a column contains numeric data (integer and/or floating point
numbers) in all rows (ignoring column names of course) then the content
of that column is right-aligned, as can be seen in the example above. The
idea here is to make it easier to compare the numbers in different
columns to each other.
- The column names are highlighted in color so they stand out a bit more
(see also :data:`.HIGHLIGHT_COLOR`). The following screen shot shows what
that looks like (my terminals are always set to white text on a black
background):
.. image:: images/pretty-table.png
"""
# Normalize the input because we'll have to iterate it more than once.
data = [normalize_columns(r, expandtabs=True) for r in data]
if column_names is not None:
column_names = normalize_columns(column_names)
if column_names:
if terminal_supports_colors():
column_names = [highlight_column_name(n) for n in column_names]
data.insert(0, column_names)
# Calculate the maximum width of each column.
widths = collections.defaultdict(int)
numeric_data = collections.defaultdict(list)
for row_index, row in enumerate(data):
for column_index, column in enumerate(row):
widths[column_index] = max(widths[column_index], ansi_width(column))
if not (column_names and row_index == 0):
numeric_data[column_index].append(bool(NUMERIC_DATA_PATTERN.match(ansi_strip(column))))
# Create a horizontal bar of dashes as a delimiter.
line_delimiter = horizontal_bar * (sum(widths.values()) + len(widths) * 3 + 1)
# Start the table with a vertical bar.
lines = [line_delimiter]
# Format the rows and columns.
for row_index, row in enumerate(data):
line = [vertical_bar]
for column_index, column in enumerate(row):
padding = ' ' * (widths[column_index] - ansi_width(column))
if all(numeric_data[column_index]):
line.append(' ' + padding + column + ' ')
else:
line.append(' ' + column + padding + ' ')
line.append(vertical_bar)
lines.append(u''.join(line))
if column_names and row_index == 0:
lines.append(line_delimiter)
# End the table with a vertical bar.
lines.append(line_delimiter)
# Join the lines, returning a single string.
return u'\n'.join(lines)
def format_robust_table(data, column_names):
"""
Render tabular data with one column per line (allowing columns with line breaks).
:param data: An iterable (e.g. a :func:`tuple` or :class:`list`)
containing the rows of the table, where each row is an
iterable containing the columns of the table (strings).
:param column_names: An iterable of column names (strings).
:returns: The rendered table (a string).
Here's an example:
>>> from humanfriendly.tables import format_robust_table
>>> column_names = ['Version', 'Uploaded on', 'Downloads']
>>> humanfriendly_releases = [
... ['1.23', '2015-05-25', '218'],
... ['1.23.1', '2015-05-26', '1354'],
... ['1.24', '2015-05-26', '223'],
... ['1.25', '2015-05-26', '4319'],
... ['1.25.1', '2015-06-02', '197'],
... ]
>>> print(format_robust_table(humanfriendly_releases, column_names))
-----------------------
Version: 1.23
Uploaded on: 2015-05-25
Downloads: 218
-----------------------
Version: 1.23.1
Uploaded on: 2015-05-26
Downloads: 1354
-----------------------
Version: 1.24
Uploaded on: 2015-05-26
Downloads: 223
-----------------------
Version: 1.25
Uploaded on: 2015-05-26
Downloads: 4319
-----------------------
Version: 1.25.1
Uploaded on: 2015-06-02
Downloads: 197
-----------------------
The column names are highlighted in bold font and color so they stand out a
bit more (see :data:`.HIGHLIGHT_COLOR`).
"""
blocks = []
column_names = ["%s:" % n for n in normalize_columns(column_names)]
if terminal_supports_colors():
column_names = [highlight_column_name(n) for n in column_names]
# Convert each row into one or more `name: value' lines (one per column)
# and group each `row of lines' into a block (i.e. rows become blocks).
for row in data:
lines = []
for column_index, column_text in enumerate(normalize_columns(row)):
stripped_column = column_text.strip()
if '\n' not in stripped_column:
# Columns without line breaks are formatted inline.
lines.append("%s %s" % (column_names[column_index], stripped_column))
else:
# Columns with line breaks could very well contain indented
# lines, so we'll put the column name on a separate line. This
# way any indentation remains intact, and it's easier to
# copy/paste the text.
lines.append(column_names[column_index])
lines.extend(column_text.rstrip().splitlines())
blocks.append(lines)
# Calculate the width of the row delimiter.
num_rows, num_columns = find_terminal_size()
longest_line = max(max(map(ansi_width, lines)) for lines in blocks)
delimiter = u"\n%s\n" % ('-' * min(longest_line, num_columns))
# Force a delimiter at the start and end of the table.
blocks.insert(0, "")
blocks.append("")
# Embed the row delimiter between every two blocks.
return delimiter.join(u"\n".join(b) for b in blocks).strip()
def format_rst_table(data, column_names=None):
"""
Render a table in reStructuredText_ format.
:param data: An iterable (e.g. a :func:`tuple` or :class:`list`)
containing the rows of the table, where each row is an
iterable containing the columns of the table (strings).
:param column_names: An iterable of column names (strings).
:returns: The rendered table (a string).
Here's an example:
>>> from humanfriendly.tables import format_rst_table
>>> column_names = ['Version', 'Uploaded on', 'Downloads']
>>> humanfriendly_releases = [
... ['1.23', '2015-05-25', '218'],
... ['1.23.1', '2015-05-26', '1354'],
... ['1.24', '2015-05-26', '223'],
... ['1.25', '2015-05-26', '4319'],
... ['1.25.1', '2015-06-02', '197'],
... ]
>>> print(format_rst_table(humanfriendly_releases, column_names))
======= =========== =========
Version Uploaded on Downloads
======= =========== =========
1.23 2015-05-25 218
1.23.1 2015-05-26 1354
1.24 2015-05-26 223
1.25 2015-05-26 4319
1.25.1 2015-06-02 197
======= =========== =========
.. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText
"""
data = [normalize_columns(r) for r in data]
if column_names:
data.insert(0, normalize_columns(column_names))
# Calculate the maximum width of each column.
widths = collections.defaultdict(int)
for row in data:
for index, column in enumerate(row):
widths[index] = max(widths[index], len(column))
# Pad the columns using whitespace.
for row in data:
for index, column in enumerate(row):
if index < (len(row) - 1):
row[index] = column.ljust(widths[index])
# Add table markers.
delimiter = ['=' * w for i, w in sorted(widths.items())]
if column_names:
data.insert(1, delimiter)
data.insert(0, delimiter)
data.append(delimiter)
# Join the lines and columns together.
return '\n'.join(' '.join(r) for r in data)
def normalize_columns(row, expandtabs=False):
results = []
for value in row:
text = coerce_string(value)
if expandtabs:
text = text.expandtabs()
results.append(text)
return results
def highlight_column_name(name):
return ansi_wrap(name, bold=True, color=HIGHLIGHT_COLOR)

776
venv/lib/python3.12/site-packages/humanfriendly/terminal/__init__.py Normal file
View File

@@ -0,0 +1,776 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: March 1, 2020
# URL: https://humanfriendly.readthedocs.io
"""
Interaction with interactive text terminals.
The :mod:`~humanfriendly.terminal` module makes it easy to interact with
interactive text terminals and format text for rendering on such terminals. If
the terms used in the documentation of this module don't make sense to you then
please refer to the `Wikipedia article on ANSI escape sequences`_ for details
about how ANSI escape sequences work.
This module was originally developed for use on UNIX systems, but since then
Windows 10 gained native support for ANSI escape sequences and this module was
enhanced to recognize and support this. For details please refer to the
:func:`enable_ansi_support()` function.
.. _Wikipedia article on ANSI escape sequences: http://en.wikipedia.org/wiki/ANSI_escape_code#Sequence_elements
"""
# Standard library modules.
import codecs
import numbers
import os
import platform
import re
import subprocess
import sys
# The `fcntl' module is platform specific so importing it may give an error. We
# hide this implementation detail from callers by handling the import error and
# setting a flag instead.
try:
import fcntl
import termios
import struct
HAVE_IOCTL = True
except ImportError:
HAVE_IOCTL = False
# Modules included in our package.
from humanfriendly.compat import coerce_string, is_unicode, on_windows, which
from humanfriendly.decorators import cached
from humanfriendly.deprecation import define_aliases
from humanfriendly.text import concatenate, format
from humanfriendly.usage import format_usage
# Public identifiers that require documentation.
__all__ = (
'ANSI_COLOR_CODES',
'ANSI_CSI',
'ANSI_ERASE_LINE',
'ANSI_HIDE_CURSOR',
'ANSI_RESET',
'ANSI_SGR',
'ANSI_SHOW_CURSOR',
'ANSI_TEXT_STYLES',
'CLEAN_OUTPUT_PATTERN',
'DEFAULT_COLUMNS',
'DEFAULT_ENCODING',
'DEFAULT_LINES',
'HIGHLIGHT_COLOR',
'ansi_strip',
'ansi_style',
'ansi_width',
'ansi_wrap',
'auto_encode',
'clean_terminal_output',
'connected_to_terminal',
'enable_ansi_support',
'find_terminal_size',
'find_terminal_size_using_ioctl',
'find_terminal_size_using_stty',
'get_pager_command',
'have_windows_native_ansi_support',
'message',
'output',
'readline_strip',
'readline_wrap',
'show_pager',
'terminal_supports_colors',
'usage',
'warning',
)
ANSI_CSI = '\x1b['
"""The ANSI "Control Sequence Introducer" (a string)."""
ANSI_SGR = 'm'
"""The ANSI "Select Graphic Rendition" sequence (a string)."""
ANSI_ERASE_LINE = '%sK' % ANSI_CSI
"""The ANSI escape sequence to erase the current line (a string)."""
ANSI_RESET = '%s0%s' % (ANSI_CSI, ANSI_SGR)
"""The ANSI escape sequence to reset styling (a string)."""
ANSI_HIDE_CURSOR = '%s?25l' % ANSI_CSI
"""The ANSI escape sequence to hide the text cursor (a string)."""
ANSI_SHOW_CURSOR = '%s?25h' % ANSI_CSI
"""The ANSI escape sequence to show the text cursor (a string)."""
ANSI_COLOR_CODES = dict(black=0, red=1, green=2, yellow=3, blue=4, magenta=5, cyan=6, white=7)
"""
A dictionary with (name, number) pairs of `portable color codes`_. Used by
:func:`ansi_style()` to generate ANSI escape sequences that change font color.
.. _portable color codes: http://en.wikipedia.org/wiki/ANSI_escape_code#Colors
"""
ANSI_TEXT_STYLES = dict(bold=1, faint=2, italic=3, underline=4, inverse=7, strike_through=9)
"""
A dictionary with (name, number) pairs of text styles (effects). Used by
:func:`ansi_style()` to generate ANSI escape sequences that change text
styles. Only widely supported text styles are included here.
"""
CLEAN_OUTPUT_PATTERN = re.compile(u'(\r|\n|\b|%s)' % re.escape(ANSI_ERASE_LINE))
"""
A compiled regular expression used to separate significant characters from other text.
This pattern is used by :func:`clean_terminal_output()` to split terminal
output into regular text versus backspace, carriage return and line feed
characters and ANSI 'erase line' escape sequences.
"""
DEFAULT_LINES = 25
"""The default number of lines in a terminal (an integer)."""
DEFAULT_COLUMNS = 80
"""The default number of columns in a terminal (an integer)."""
DEFAULT_ENCODING = 'UTF-8'
"""The output encoding for Unicode strings."""
HIGHLIGHT_COLOR = os.environ.get('HUMANFRIENDLY_HIGHLIGHT_COLOR', 'green')
"""
The color used to highlight important tokens in formatted text (e.g. the usage
message of the ``humanfriendly`` program). If the environment variable
``$HUMANFRIENDLY_HIGHLIGHT_COLOR`` is set it determines the value of
:data:`HIGHLIGHT_COLOR`.
"""
def ansi_strip(text, readline_hints=True):
"""
Strip ANSI escape sequences from the given string.
:param text: The text from which ANSI escape sequences should be removed (a
string).
:param readline_hints: If :data:`True` then :func:`readline_strip()` is
used to remove `readline hints`_ from the string.
:returns: The text without ANSI escape sequences (a string).
"""
pattern = '%s.*?%s' % (re.escape(ANSI_CSI), re.escape(ANSI_SGR))
text = re.sub(pattern, '', text)
if readline_hints:
text = readline_strip(text)
return text
def ansi_style(**kw):
"""
Generate ANSI escape sequences for the given color and/or style(s).
:param color: The foreground color. Three types of values are supported:
- The name of a color (one of the strings 'black', 'red',
'green', 'yellow', 'blue', 'magenta', 'cyan' or 'white').
- An integer that refers to the 256 color mode palette.
- A tuple or list with three integers representing an RGB
(red, green, blue) value.
The value :data:`None` (the default) means no escape
sequence to switch color will be emitted.
:param background: The background color (see the description
of the `color` argument).
:param bright: Use high intensity colors instead of default colors
(a boolean, defaults to :data:`False`).
:param readline_hints: If :data:`True` then :func:`readline_wrap()` is
applied to the generated ANSI escape sequences (the
default is :data:`False`).
:param kw: Any additional keyword arguments are expected to match a key
in the :data:`ANSI_TEXT_STYLES` dictionary. If the argument's
value evaluates to :data:`True` the respective style will be
enabled.
:returns: The ANSI escape sequences to enable the requested text styles or
an empty string if no styles were requested.
:raises: :exc:`~exceptions.ValueError` when an invalid color name is given.
Even though only eight named colors are supported, the use of `bright=True`
and `faint=True` increases the number of available colors to around 24 (it
may be slightly lower, for example because faint black is just black).
**Support for 8-bit colors**
In `release 4.7`_ support for 256 color mode was added. While this
significantly increases the available colors it's not very human friendly
in usage because you need to look up color codes in the `256 color mode
palette <https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit>`_.
You can use the ``humanfriendly --demo`` command to get a demonstration of
the available colors, see also the screen shot below. Note that the small
font size in the screen shot was so that the demonstration of 256 color
mode support would fit into a single screen shot without scrolling :-)
(I wasn't feeling very creative).
.. image:: images/ansi-demo.png
**Support for 24-bit colors**
In `release 4.14`_ support for 24-bit colors was added by accepting a tuple
or list with three integers representing the RGB (red, green, blue) value
of a color. This is not included in the demo because rendering millions of
colors was deemed unpractical ;-).
.. _release 4.7: http://humanfriendly.readthedocs.io/en/latest/changelog.html#release-4-7-2018-01-14
.. _release 4.14: http://humanfriendly.readthedocs.io/en/latest/changelog.html#release-4-14-2018-07-13
"""
# Start with sequences that change text styles.
sequences = [ANSI_TEXT_STYLES[k] for k, v in kw.items() if k in ANSI_TEXT_STYLES and v]
# Append the color code (if any).
for color_type in 'color', 'background':
color_value = kw.get(color_type)
if isinstance(color_value, (tuple, list)):
if len(color_value) != 3:
msg = "Invalid color value %r! (expected tuple or list with three numbers)"
raise ValueError(msg % color_value)
sequences.append(48 if color_type == 'background' else 38)
sequences.append(2)
sequences.extend(map(int, color_value))
elif isinstance(color_value, numbers.Number):
# Numeric values are assumed to be 256 color codes.
sequences.extend((
39 if color_type == 'background' else 38,
5, int(color_value)
))
elif color_value:
# Other values are assumed to be strings containing one of the known color names.
if color_value not in ANSI_COLOR_CODES:
msg = "Invalid color value %r! (expected an integer or one of the strings %s)"
raise ValueError(msg % (color_value, concatenate(map(repr, sorted(ANSI_COLOR_CODES)))))
# Pick the right offset for foreground versus background
# colors and regular intensity versus bright colors.
offset = (
(100 if kw.get('bright') else 40)
if color_type == 'background'
else (90 if kw.get('bright') else 30)
)
# Combine the offset and color code into a single integer.
sequences.append(offset + ANSI_COLOR_CODES[color_value])
if sequences:
encoded = ANSI_CSI + ';'.join(map(str, sequences)) + ANSI_SGR
return readline_wrap(encoded) if kw.get('readline_hints') else encoded
else:
return ''
def ansi_width(text):
"""
Calculate the effective width of the given text (ignoring ANSI escape sequences).
:param text: The text whose width should be calculated (a string).
:returns: The width of the text without ANSI escape sequences (an
integer).
This function uses :func:`ansi_strip()` to strip ANSI escape sequences from
the given string and returns the length of the resulting string.
"""
return len(ansi_strip(text))
def ansi_wrap(text, **kw):
"""
Wrap text in ANSI escape sequences for the given color and/or style(s).
:param text: The text to wrap (a string).
:param kw: Any keyword arguments are passed to :func:`ansi_style()`.
:returns: The result of this function depends on the keyword arguments:
- If :func:`ansi_style()` generates an ANSI escape sequence based
on the keyword arguments, the given text is prefixed with the
generated ANSI escape sequence and suffixed with
:data:`ANSI_RESET`.
- If :func:`ansi_style()` returns an empty string then the text
given by the caller is returned unchanged.
"""
start_sequence = ansi_style(**kw)
if start_sequence:
end_sequence = ANSI_RESET
if kw.get('readline_hints'):
end_sequence = readline_wrap(end_sequence)
return start_sequence + text + end_sequence
else:
return text
def auto_encode(stream, text, *args, **kw):
"""
Reliably write Unicode strings to the terminal.
:param stream: The file-like object to write to (a value like
:data:`sys.stdout` or :data:`sys.stderr`).
:param text: The text to write to the stream (a string).
:param args: Refer to :func:`~humanfriendly.text.format()`.
:param kw: Refer to :func:`~humanfriendly.text.format()`.
Renders the text using :func:`~humanfriendly.text.format()` and writes it
to the given stream. If an :exc:`~exceptions.UnicodeEncodeError` is
encountered in doing so, the text is encoded using :data:`DEFAULT_ENCODING`
and the write is retried. The reasoning behind this rather blunt approach
is that it's preferable to get output on the command line in the wrong
encoding then to have the Python program blow up with a
:exc:`~exceptions.UnicodeEncodeError` exception.
"""
text = format(text, *args, **kw)
try:
stream.write(text)
except UnicodeEncodeError:
stream.write(codecs.encode(text, DEFAULT_ENCODING))
def clean_terminal_output(text):
"""
Clean up the terminal output of a command.
:param text: The raw text with special characters (a Unicode string).
:returns: A list of Unicode strings (one for each line).
This function emulates the effect of backspace (0x08), carriage return
(0x0D) and line feed (0x0A) characters and the ANSI 'erase line' escape
sequence on interactive terminals. It's intended to clean up command output
that was originally meant to be rendered on an interactive terminal and
that has been captured using e.g. the :man:`script` program [#]_ or the
:mod:`pty` module [#]_.
.. [#] My coloredlogs_ package supports the ``coloredlogs --to-html``
command which uses :man:`script` to fool a subprocess into thinking
that it's connected to an interactive terminal (in order to get it
to emit ANSI escape sequences).
.. [#] My capturer_ package uses the :mod:`pty` module to fool the current
process and subprocesses into thinking they are connected to an
interactive terminal (in order to get them to emit ANSI escape
sequences).
**Some caveats about the use of this function:**
- Strictly speaking the effect of carriage returns cannot be emulated
outside of an actual terminal due to the interaction between overlapping
output, terminal widths and line wrapping. The goal of this function is
to sanitize noise in terminal output while preserving useful output.
Think of it as a useful and pragmatic but possibly lossy conversion.
- The algorithm isn't smart enough to properly handle a pair of ANSI escape
sequences that open before a carriage return and close after the last
carriage return in a linefeed delimited string; the resulting string will
contain only the closing end of the ANSI escape sequence pair. Tracking
this kind of complexity requires a state machine and proper parsing.
.. _capturer: https://pypi.org/project/capturer
.. _coloredlogs: https://pypi.org/project/coloredlogs
"""
cleaned_lines = []
current_line = ''
current_position = 0
for token in CLEAN_OUTPUT_PATTERN.split(text):
if token == '\r':
# Seek back to the start of the current line.
current_position = 0
elif token == '\b':
# Seek back one character in the current line.
current_position = max(0, current_position - 1)
else:
if token == '\n':
# Capture the current line.
cleaned_lines.append(current_line)
if token in ('\n', ANSI_ERASE_LINE):
# Clear the current line.
current_line = ''
current_position = 0
elif token:
# Merge regular output into the current line.
new_position = current_position + len(token)
prefix = current_line[:current_position]
suffix = current_line[new_position:]
current_line = prefix + token + suffix
current_position = new_position
# Capture the last line (if any).
cleaned_lines.append(current_line)
# Remove any empty trailing lines.
while cleaned_lines and not cleaned_lines[-1]:
cleaned_lines.pop(-1)
return cleaned_lines
def connected_to_terminal(stream=None):
"""
Check if a stream is connected to a terminal.
:param stream: The stream to check (a file-like object,
defaults to :data:`sys.stdout`).
:returns: :data:`True` if the stream is connected to a terminal,
:data:`False` otherwise.
See also :func:`terminal_supports_colors()`.
"""
stream = sys.stdout if stream is None else stream
try:
return stream.isatty()
except Exception:
return False
@cached
def enable_ansi_support():
"""
Try to enable support for ANSI escape sequences (required on Windows).
:returns: :data:`True` if ANSI is supported, :data:`False` otherwise.
This functions checks for the following supported configurations, in the
given order:
1. On Windows, if :func:`have_windows_native_ansi_support()` confirms
native support for ANSI escape sequences :mod:`ctypes` will be used to
enable this support.
2. On Windows, if the environment variable ``$ANSICON`` is set nothing is
done because it is assumed that support for ANSI escape sequences has
already been enabled via `ansicon <https://github.com/adoxa/ansicon>`_.
3. On Windows, an attempt is made to import and initialize the Python
package :pypi:`colorama` instead (of course for this to work
:pypi:`colorama` has to be installed).
4. On other platforms this function calls :func:`connected_to_terminal()`
to determine whether ANSI escape sequences are supported (that is to
say all platforms that are not Windows are assumed to support ANSI
escape sequences natively, without weird contortions like above).
This makes it possible to call :func:`enable_ansi_support()`
unconditionally without checking the current platform.
The :func:`~humanfriendly.decorators.cached` decorator is used to ensure
that this function is only executed once, but its return value remains
available on later calls.
"""
if have_windows_native_ansi_support():
import ctypes
ctypes.windll.kernel32.SetConsoleMode(ctypes.windll.kernel32.GetStdHandle(-11), 7)
ctypes.windll.kernel32.SetConsoleMode(ctypes.windll.kernel32.GetStdHandle(-12), 7)
return True
elif on_windows():
if 'ANSICON' in os.environ:
return True
try:
import colorama
colorama.init()
return True
except ImportError:
return False
else:
return connected_to_terminal()
def find_terminal_size():
"""
Determine the number of lines and columns visible in the terminal.
:returns: A tuple of two integers with the line and column count.
The result of this function is based on the first of the following three
methods that works:
1. First :func:`find_terminal_size_using_ioctl()` is tried,
2. then :func:`find_terminal_size_using_stty()` is tried,
3. finally :data:`DEFAULT_LINES` and :data:`DEFAULT_COLUMNS` are returned.
.. note:: The :func:`find_terminal_size()` function performs the steps
above every time it is called, the result is not cached. This is
because the size of a virtual terminal can change at any time and
the result of :func:`find_terminal_size()` should be correct.
`Pre-emptive snarky comment`_: It's possible to cache the result
of this function and use :mod:`signal.SIGWINCH <signal>` to
refresh the cached values!
Response: As a library I don't consider it the role of the
: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
"""
# The first method. Any of the standard streams may have been redirected
# somewhere and there's no telling which, so we'll just try them all.
for stream in sys.stdin, sys.stdout, sys.stderr:
try:
result = find_terminal_size_using_ioctl(stream)
if min(result) >= 1:
return result
except Exception:
pass
# The second method.
try:
result = find_terminal_size_using_stty()
if min(result) >= 1:
return result
except Exception:
pass
# Fall back to conservative defaults.
return DEFAULT_LINES, DEFAULT_COLUMNS
def find_terminal_size_using_ioctl(stream):
"""
Find the terminal size using :func:`fcntl.ioctl()`.
:param stream: A stream connected to the terminal (a file object with a
``fileno`` attribute).
:returns: A tuple of two integers with the line and column count.
:raises: This function can raise exceptions but I'm not going to document
them here, you should be using :func:`find_terminal_size()`.
Based on an `implementation found on StackOverflow <http://stackoverflow.com/a/3010495/788200>`_.
"""
if not HAVE_IOCTL:
raise NotImplementedError("It looks like the `fcntl' module is not available!")
h, w, hp, wp = struct.unpack('HHHH', fcntl.ioctl(stream, termios.TIOCGWINSZ, struct.pack('HHHH', 0, 0, 0, 0)))
return h, w
def find_terminal_size_using_stty():
"""
Find the terminal size using the external command ``stty size``.
:param stream: A stream connected to the terminal (a file object).
:returns: A tuple of two integers with the line and column count.
:raises: This function can raise exceptions but I'm not going to document
them here, you should be using :func:`find_terminal_size()`.
"""
stty = subprocess.Popen(['stty', 'size'],
stdout=subprocess.PIPE,
stderr=subprocess.PIPE)
stdout, stderr = stty.communicate()
tokens = stdout.split()
if len(tokens) != 2:
raise Exception("Invalid output from `stty size'!")
return tuple(map(int, tokens))
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 :man:`less` is used).
When the selected pager is :man:`less`, the following options are used to
make the experience more user friendly:
- ``--quit-if-one-screen`` causes :man:`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 :man:`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.
"""
# 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
@cached
def have_windows_native_ansi_support():
"""
Check if we're running on a Windows 10 release with native support for ANSI escape sequences.
:returns: :data:`True` if so, :data:`False` otherwise.
The :func:`~humanfriendly.decorators.cached` decorator is used as a minor
performance optimization. Semantically this should have zero impact because
the answer doesn't change in the lifetime of a computer process.
"""
if on_windows():
try:
# I can't be 100% sure this will never break and I'm not in a
# position to test it thoroughly either, so I decided that paying
# the price of one additional try / except statement is worth the
# additional peace of mind :-).
components = tuple(int(c) for c in platform.version().split('.'))
return components >= (10, 0, 14393)
except Exception:
pass
return False
def message(text, *args, **kw):
"""
Print a formatted message to the standard error stream.
For details about argument handling please refer to
:func:`~humanfriendly.text.format()`.
Renders the message using :func:`~humanfriendly.text.format()` and writes
the resulting string (followed by a newline) to :data:`sys.stderr` using
:func:`auto_encode()`.
"""
auto_encode(sys.stderr, coerce_string(text) + '\n', *args, **kw)
def output(text, *args, **kw):
"""
Print a formatted message to the standard output stream.
For details about argument handling please refer to
:func:`~humanfriendly.text.format()`.
Renders the message using :func:`~humanfriendly.text.format()` and writes
the resulting string (followed by a newline) to :data:`sys.stdout` using
:func:`auto_encode()`.
"""
auto_encode(sys.stdout, coerce_string(text) + '\n', *args, **kw)
def readline_strip(expr):
"""
Remove `readline hints`_ from a string.
:param text: The text to strip (a string).
:returns: The stripped text.
"""
return expr.replace('\001', '').replace('\002', '')
def readline_wrap(expr):
"""
Wrap an ANSI escape sequence in `readline hints`_.
:param text: The text with the escape sequence to wrap (a string).
:returns: The wrapped text.
.. _readline hints: http://superuser.com/a/301355
"""
return '\001' + expr + '\002'
def show_pager(formatted_text, encoding=DEFAULT_ENCODING):
"""
Print a large text to the terminal using a pager.
:param formatted_text: The text to print to the terminal (a string).
:param encoding: The name of the text encoding used to encode the formatted
text if the formatted text is a Unicode string (a string,
defaults to :data:`DEFAULT_ENCODING`).
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).
Refer to :func:`get_pager_command()` for details about the command line
that's used to invoke the pager.
"""
if connected_to_terminal():
# Make sure the selected pager command is available.
command_line = get_pager_command(formatted_text)
if which(command_line[0]):
pager = subprocess.Popen(command_line, stdin=subprocess.PIPE)
if is_unicode(formatted_text):
formatted_text = formatted_text.encode(encoding)
pager.communicate(input=formatted_text)
return
output(formatted_text)
def terminal_supports_colors(stream=None):
"""
Check if a stream is connected to a terminal that supports ANSI escape sequences.
:param stream: The stream to check (a file-like object,
defaults to :data:`sys.stdout`).
:returns: :data:`True` if the terminal supports ANSI escape sequences,
:data:`False` otherwise.
This function was originally inspired by the implementation of
`django.core.management.color.supports_color()
<https://github.com/django/django/blob/master/django/core/management/color.py>`_
but has since evolved significantly.
"""
if on_windows():
# On Windows support for ANSI escape sequences is not a given.
have_ansicon = 'ANSICON' in os.environ
have_colorama = 'colorama' in sys.modules
have_native_support = have_windows_native_ansi_support()
if not (have_ansicon or have_colorama or have_native_support):
return False
return connected_to_terminal(stream)
def usage(usage_text):
"""
Print a human friendly usage message to the terminal.
:param text: The usage message to print (a string).
This function does two things:
1. If :data:`sys.stdout` is connected to a terminal (see
:func:`connected_to_terminal()`) then the usage message is formatted
using :func:`.format_usage()`.
2. The usage message is shown using a pager (see :func:`show_pager()`).
"""
if terminal_supports_colors(sys.stdout):
usage_text = format_usage(usage_text)
show_pager(usage_text)
def warning(text, *args, **kw):
"""
Show a warning message on the terminal.
For details about argument handling please refer to
:func:`~humanfriendly.text.format()`.
Renders the message using :func:`~humanfriendly.text.format()` and writes
the resulting string (followed by a newline) to :data:`sys.stderr` using
:func:`auto_encode()`.
If :data:`sys.stderr` is connected to a terminal that supports colors,
:func:`ansi_wrap()` is used to color the message in a red font (to make
the warning stand out from surrounding text).
"""
text = coerce_string(text)
if terminal_supports_colors(sys.stderr):
text = ansi_wrap(text, color='red')
auto_encode(sys.stderr, text + '\n', *args, **kw)
# Define aliases for backwards compatibility.
define_aliases(
module_name=__name__,
# In humanfriendly 1.31 the find_meta_variables() and format_usage()
# functions were extracted to the new module humanfriendly.usage.
find_meta_variables='humanfriendly.usage.find_meta_variables',
format_usage='humanfriendly.usage.format_usage',
# In humanfriendly 8.0 the html_to_ansi() function and HTMLConverter
# class were extracted to the new module humanfriendly.terminal.html.
html_to_ansi='humanfriendly.terminal.html.html_to_ansi',
HTMLConverter='humanfriendly.terminal.html.HTMLConverter',
)

BIN
venv/lib/python3.12/site-packages/humanfriendly/terminal/__pycache__/__init__.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/terminal/__pycache__/html.cpython-312.pyc Normal file
View File

Binary file not shown.

BIN
venv/lib/python3.12/site-packages/humanfriendly/terminal/__pycache__/spinners.cpython-312.pyc Normal file
View File

Binary file not shown.

423
venv/lib/python3.12/site-packages/humanfriendly/terminal/html.py Normal file
View File

@@ -0,0 +1,423 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: February 29, 2020
# URL: https://humanfriendly.readthedocs.io
"""Convert HTML with simple text formatting to text with ANSI escape sequences."""
# Standard library modules.
import re
# Modules included in our package.
from humanfriendly.compat import HTMLParser, StringIO, name2codepoint, unichr
from humanfriendly.text import compact_empty_lines
from humanfriendly.terminal import ANSI_COLOR_CODES, ANSI_RESET, ansi_style
# Public identifiers that require documentation.
__all__ = ('HTMLConverter', 'html_to_ansi')
def html_to_ansi(data, callback=None):
"""
Convert HTML with simple text formatting to text with ANSI escape sequences.
:param data: The HTML to convert (a string).
:param callback: Optional callback to pass to :class:`HTMLConverter`.
:returns: Text with ANSI escape sequences (a string).
Please refer to the documentation of the :class:`HTMLConverter` class for
details about the conversion process (like which tags are supported) and an
example with a screenshot.
"""
converter = HTMLConverter(callback=callback)
return converter(data)
class HTMLConverter(HTMLParser):
"""
Convert HTML with simple text formatting to text with ANSI escape sequences.
The following text styles are supported:
- Bold: ``<b>``, ``<strong>`` and ``<span style="font-weight: bold;">``
- Italic: ``<i>``, ``<em>`` and ``<span style="font-style: italic;">``
- Strike-through: ``<del>``, ``<s>`` and ``<span style="text-decoration: line-through;">``
- Underline: ``<ins>``, ``<u>`` and ``<span style="text-decoration: underline">``
Colors can be specified as follows:
- Foreground color: ``<span style="color: #RRGGBB;">``
- Background color: ``<span style="background-color: #RRGGBB;">``
Here's a small demonstration:
.. code-block:: python
from humanfriendly.text import dedent
from humanfriendly.terminal import html_to_ansi
print(html_to_ansi(dedent('''
<b>Hello world!</b>
<i>Is this thing on?</i>
I guess I can <u>underline</u> or <s>strike-through</s> text?
And what about <span style="color: red">color</span>?
''')))
rainbow_colors = [
'#FF0000', '#E2571E', '#FF7F00', '#FFFF00', '#00FF00',
'#96BF33', '#0000FF', '#4B0082', '#8B00FF', '#FFFFFF',
]
html_rainbow = "".join('<span style="color: %s">o</span>' % c for c in rainbow_colors)
print(html_to_ansi("Let's try a rainbow: %s" % html_rainbow))
Here's what the results look like:
.. image:: images/html-to-ansi.png
Some more details:
- Nested tags are supported, within reasonable limits.
- Text in ``<code>`` and ``<pre>`` tags will be highlighted in a
different color from the main text (currently this is yellow).
- ``<a href="URL">TEXT</a>`` is converted to the format "TEXT (URL)" where
the uppercase symbols are highlighted in light blue with an underline.
- ``<div>``, ``<p>`` and ``<pre>`` tags are considered block level tags
and are wrapped in vertical whitespace to prevent their content from
"running into" surrounding text. This may cause runs of multiple empty
lines to be emitted. As a *workaround* the :func:`__call__()` method
will automatically call :func:`.compact_empty_lines()` on the generated
output before returning it to the caller. Of course this won't work
when `output` is set to something like :data:`sys.stdout`.
- ``<br>`` is converted to a single plain text line break.
Implementation notes:
- A list of dictionaries with style information is used as a stack where
new styling can be pushed and a pop will restore the previous styling.
When new styling is pushed, it is merged with (but overrides) the current
styling.
- If you're going to be converting a lot of HTML it might be useful from
a performance standpoint to re-use an existing :class:`HTMLConverter`
object for unrelated HTML fragments, in this case take a look at the
:func:`__call__()` method (it makes this use case very easy).
.. versionadded:: 4.15
:class:`humanfriendly.terminal.HTMLConverter` was added to the
`humanfriendly` package during the initial development of my new
`chat-archive <https://chat-archive.readthedocs.io/>`_ project, whose
command line interface makes for a great demonstration of the
flexibility that this feature provides (hint: check out how the search
keyword highlighting combines with the regular highlighting).
"""
BLOCK_TAGS = ('div', 'p', 'pre')
"""The names of tags that are padded with vertical whitespace."""
def __init__(self, *args, **kw):
"""
Initialize an :class:`HTMLConverter` object.
:param callback: Optional keyword argument to specify a function that
will be called to process text fragments before they
are emitted on the output stream. Note that link text
and preformatted text fragments are not processed by
this callback.
:param output: Optional keyword argument to redirect the output to the
given file-like object. If this is not given a new
:class:`~python3:io.StringIO` object is created.
"""
# Hide our optional keyword arguments from the superclass.
self.callback = kw.pop("callback", None)
self.output = kw.pop("output", None)
# Initialize the superclass.
HTMLParser.__init__(self, *args, **kw)
def __call__(self, data):
"""
Reset the parser, convert some HTML and get the text with ANSI escape sequences.
:param data: The HTML to convert to text (a string).
:returns: The converted text (only in case `output` is
a :class:`~python3:io.StringIO` object).
"""
self.reset()
self.feed(data)
self.close()
if isinstance(self.output, StringIO):
return compact_empty_lines(self.output.getvalue())
@property
def current_style(self):
"""Get the current style from the top of the stack (a dictionary)."""
return self.stack[-1] if self.stack else {}
def close(self):
"""
Close previously opened ANSI escape sequences.
This method overrides the same method in the superclass to ensure that
an :data:`.ANSI_RESET` code is emitted when parsing reaches the end of
the input but a style is still active. This is intended to prevent
malformed HTML from messing up terminal output.
"""
if any(self.stack):
self.output.write(ANSI_RESET)
self.stack = []
HTMLParser.close(self)
def emit_style(self, style=None):
"""
Emit an ANSI escape sequence for the given or current style to the output stream.
:param style: A dictionary with arguments for :func:`.ansi_style()` or
:data:`None`, in which case the style at the top of the
stack is emitted.
"""
# Clear the current text styles.
self.output.write(ANSI_RESET)
# Apply a new text style?
style = self.current_style if style is None else style
if style:
self.output.write(ansi_style(**style))
def handle_charref(self, value):
"""
Process a decimal or hexadecimal numeric character reference.
:param value: The decimal or hexadecimal value (a string).
"""
self.output.write(unichr(int(value[1:], 16) if value.startswith('x') else int(value)))
def handle_data(self, data):
"""
Process textual data.
:param data: The decoded text (a string).
"""
if self.link_url:
# Link text is captured literally so that we can reliably check
# whether the text and the URL of the link are the same string.
self.link_text = data
elif self.callback and self.preformatted_text_level == 0:
# Text that is not part of a link and not preformatted text is
# passed to the user defined callback to allow for arbitrary
# pre-processing.
data = self.callback(data)
# All text is emitted unmodified on the output stream.
self.output.write(data)
def handle_endtag(self, tag):
"""
Process the end of an HTML tag.
:param tag: The name of the tag (a string).
"""
if tag in ('a', 'b', 'code', 'del', 'em', 'i', 'ins', 'pre', 's', 'strong', 'span', 'u'):
old_style = self.current_style
# The following conditional isn't necessary for well formed
# HTML but prevents raising exceptions on malformed HTML.
if self.stack:
self.stack.pop(-1)
new_style = self.current_style
if tag == 'a':
if self.urls_match(self.link_text, self.link_url):
# Don't render the URL when it's part of the link text.
self.emit_style(new_style)
else:
self.emit_style(new_style)
self.output.write(' (')
self.emit_style(old_style)
self.output.write(self.render_url(self.link_url))
self.emit_style(new_style)
self.output.write(')')
else:
self.emit_style(new_style)
if tag in ('code', 'pre'):
self.preformatted_text_level -= 1
if tag in self.BLOCK_TAGS:
# Emit an empty line after block level tags.
self.output.write('\n\n')
def handle_entityref(self, name):
"""
Process a named character reference.
:param name: The name of the character reference (a string).
"""
self.output.write(unichr(name2codepoint[name]))
def handle_starttag(self, tag, attrs):
"""
Process the start of an HTML tag.
:param tag: The name of the tag (a string).
:param attrs: A list of tuples with two strings each.
"""
if tag in self.BLOCK_TAGS:
# Emit an empty line before block level tags.
self.output.write('\n\n')
if tag == 'a':
self.push_styles(color='blue', bright=True, underline=True)
# Store the URL that the link points to for later use, so that we
# can render the link text before the URL (with the reasoning that
# this is the most intuitive way to present a link in a plain text
# interface).
self.link_url = next((v for n, v in attrs if n == 'href'), '')
elif tag == 'b' or tag == 'strong':
self.push_styles(bold=True)
elif tag == 'br':
self.output.write('\n')
elif tag == 'code' or tag == 'pre':
self.push_styles(color='yellow')
self.preformatted_text_level += 1
elif tag == 'del' or tag == 's':
self.push_styles(strike_through=True)
elif tag == 'em' or tag == 'i':
self.push_styles(italic=True)
elif tag == 'ins' or tag == 'u':
self.push_styles(underline=True)
elif tag == 'span':
styles = {}
css = next((v for n, v in attrs if n == 'style'), "")
for rule in css.split(';'):
name, _, value = rule.partition(':')
name = name.strip()
value = value.strip()
if name == 'background-color':
styles['background'] = self.parse_color(value)
elif name == 'color':
styles['color'] = self.parse_color(value)
elif name == 'font-style' and value == 'italic':
styles['italic'] = True
elif name == 'font-weight' and value == 'bold':
styles['bold'] = True
elif name == 'text-decoration' and value == 'line-through':
styles['strike_through'] = True
elif name == 'text-decoration' and value == 'underline':
styles['underline'] = True
self.push_styles(**styles)
def normalize_url(self, url):
"""
Normalize a URL to enable string equality comparison.
:param url: The URL to normalize (a string).
:returns: The normalized URL (a string).
"""
return re.sub('^mailto:', '', url)
def parse_color(self, value):
"""
Convert a CSS color to something that :func:`.ansi_style()` understands.
:param value: A string like ``rgb(1,2,3)``, ``#AABBCC`` or ``yellow``.
:returns: A color value supported by :func:`.ansi_style()` or :data:`None`.
"""
# Parse an 'rgb(N,N,N)' expression.
if value.startswith('rgb'):
tokens = re.findall(r'\d+', value)
if len(tokens) == 3:
return tuple(map(int, tokens))
# Parse an '#XXXXXX' expression.
elif value.startswith('#'):
value = value[1:]
length = len(value)
if length == 6:
# Six hex digits (proper notation).
return (
int(value[:2], 16),
int(value[2:4], 16),
int(value[4:6], 16),
)
elif length == 3:
# Three hex digits (shorthand).
return (
int(value[0], 16),
int(value[1], 16),
int(value[2], 16),
)
# Try to recognize a named color.
value = value.lower()
if value in ANSI_COLOR_CODES:
return value
def push_styles(self, **changes):
"""
Push new style information onto the stack.
:param changes: Any keyword arguments are passed on to :func:`.ansi_style()`.
This method is a helper for :func:`handle_starttag()`
that does the following:
1. Make a copy of the current styles (from the top of the stack),
2. Apply the given `changes` to the copy of the current styles,
3. Add the new styles to the stack,
4. Emit the appropriate ANSI escape sequence to the output stream.
"""
prototype = self.current_style
if prototype:
new_style = dict(prototype)
new_style.update(changes)
else:
new_style = changes
self.stack.append(new_style)
self.emit_style(new_style)
def render_url(self, url):
"""
Prepare a URL for rendering on the terminal.
:param url: The URL to simplify (a string).
:returns: The simplified URL (a string).
This method pre-processes a URL before rendering on the terminal. The
following modifications are made:
- The ``mailto:`` prefix is stripped.
- Spaces are converted to ``%20``.
- A trailing parenthesis is converted to ``%29``.
"""
url = re.sub('^mailto:', '', url)
url = re.sub(' ', '%20', url)
url = re.sub(r'\)$', '%29', url)
return url
def reset(self):
"""
Reset the state of the HTML parser and ANSI converter.
When `output` is a :class:`~python3:io.StringIO` object a new
instance will be created (and the old one garbage collected).
"""
# Reset the state of the superclass.
HTMLParser.reset(self)
# Reset our instance variables.
self.link_text = None
self.link_url = None
self.preformatted_text_level = 0
if self.output is None or isinstance(self.output, StringIO):
# If the caller specified something like output=sys.stdout then it
# doesn't make much sense to negate that choice here in reset().
self.output = StringIO()
self.stack = []
def urls_match(self, a, b):
"""
Compare two URLs for equality using :func:`normalize_url()`.
:param a: A string containing a URL.
:param b: A string containing a URL.
:returns: :data:`True` if the URLs are the same, :data:`False` otherwise.
This method is used by :func:`handle_endtag()` to omit the URL of a
hyperlink (``<a href="...">``) when the link text is that same URL.
"""
return self.normalize_url(a) == self.normalize_url(b)

310
venv/lib/python3.12/site-packages/humanfriendly/terminal/spinners.py Normal file
View File

@@ -0,0 +1,310 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: March 1, 2020
# URL: https://humanfriendly.readthedocs.io
"""
Support for spinners that represent progress on interactive terminals.
The :class:`Spinner` class shows a "spinner" on the terminal to let the user
know that something is happening during long running operations that would
otherwise be silent (leaving the user to wonder what they're waiting for).
Below are some visual examples that should illustrate the point.
**Simple spinners:**
Here's a screen capture that shows the simplest form of spinner:
.. image:: images/spinner-basic.gif
:alt: Animated screen capture of a simple spinner.
The following code was used to create the spinner above:
.. code-block:: python
import itertools
import time
from humanfriendly import Spinner
with Spinner(label="Downloading") as spinner:
for i in itertools.count():
# Do something useful here.
time.sleep(0.1)
# Advance the spinner.
spinner.step()
**Spinners that show elapsed time:**
Here's a spinner that shows the elapsed time since it started:
.. image:: images/spinner-with-timer.gif
:alt: Animated screen capture of a spinner showing elapsed time.
The following code was used to create the spinner above:
.. code-block:: python
import itertools
import time
from humanfriendly import Spinner, Timer
with Spinner(label="Downloading", timer=Timer()) as spinner:
for i in itertools.count():
# Do something useful here.
time.sleep(0.1)
# Advance the spinner.
spinner.step()
**Spinners that show progress:**
Here's a spinner that shows a progress percentage:
.. image:: images/spinner-with-progress.gif
:alt: Animated screen capture of spinner showing progress.
The following code was used to create the spinner above:
.. code-block:: python
import itertools
import random
import time
from humanfriendly import Spinner, Timer
with Spinner(label="Downloading", total=100) as spinner:
progress = 0
while progress < 100:
# Do something useful here.
time.sleep(0.1)
# Advance the spinner.
spinner.step(progress)
# Determine the new progress value.
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 :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 :func:`Spinner.clear()`
when the spinner ends.
"""
# Standard library modules.
import multiprocessing
import sys
import time
# Modules included in our package.
from humanfriendly import Timer
from humanfriendly.deprecation import deprecated_args
from humanfriendly.terminal import ANSI_ERASE_LINE
# Public identifiers that require documentation.
__all__ = ("AutomaticSpinner", "GLYPHS", "MINIMUM_INTERVAL", "Spinner")
GLYPHS = ["-", "\\", "|", "/"]
"""A list of strings with characters that together form a crude animation :-)."""
MINIMUM_INTERVAL = 0.2
"""Spinners are redrawn with a frequency no higher than this number (a floating point number of seconds)."""
class Spinner(object):
"""Show a spinner on the terminal as a simple means of feedback to the user."""
@deprecated_args('label', 'total', 'stream', 'interactive', 'timer')
def __init__(self, **options):
"""
Initialize a :class:`Spinner` object.
:param label:
The label for the spinner (a string or :data:`None`, defaults to
:data:`None`).
:param total:
The expected number of steps (an integer or :data:`None`). If this is
provided the spinner will show a progress percentage.
:param stream:
The output stream to show the spinner on (a file-like object,
defaults to :data:`sys.stderr`).
:param interactive:
:data:`True` to enable rendering of the spinner, :data:`False` to
disable (defaults to the result of ``stream.isatty()``).
:param timer:
A :class:`.Timer` object (optional). If this is given the spinner
will show the elapsed time according to the timer.
:param interval:
The spinner will be updated at most once every this many seconds
(a floating point number, defaults to :data:`MINIMUM_INTERVAL`).
:param glyphs:
A list of strings with single characters that are drawn in the same
place in succession to implement a simple animated effect (defaults
to :data:`GLYPHS`).
"""
# Store initializer arguments.
self.interactive = options.get('interactive')
self.interval = options.get('interval', MINIMUM_INTERVAL)
self.label = options.get('label')
self.states = options.get('glyphs', GLYPHS)
self.stream = options.get('stream', sys.stderr)
self.timer = options.get('timer')
self.total = options.get('total')
# Define instance variables.
self.counter = 0
self.last_update = 0
# Try to automatically discover whether the stream is connected to
# a terminal, but don't fail if no isatty() method is available.
if self.interactive is None:
try:
self.interactive = self.stream.isatty()
except Exception:
self.interactive = False
def step(self, progress=0, label=None):
"""
Advance the spinner by one step and redraw it.
:param progress: The number of the current step, relative to the total
given to the :class:`Spinner` constructor (an integer,
optional). If not provided the spinner will not show
progress.
:param label: The label to use while redrawing (a string, optional). If
not provided the label given to the :class:`Spinner`
constructor is used instead.
This method advances the spinner by one step without starting a new
line, causing an animated effect which is very simple but much nicer
than waiting for a prompt which is completely silent for a long time.
.. note:: This method uses time based rate limiting to avoid redrawing
the spinner too frequently. If you know you're dealing with
code that will call :func:`step()` at a high frequency,
consider using :func:`sleep()` to avoid creating the
equivalent of a busy loop that's rate limiting the spinner
99% of the time.
"""
if self.interactive:
time_now = time.time()
if time_now - self.last_update >= self.interval:
self.last_update = time_now
state = self.states[self.counter % len(self.states)]
label = label or self.label
if not label:
raise Exception("No label set for spinner!")
elif self.total and progress:
label = "%s: %.2f%%" % (label, progress / (self.total / 100.0))
elif self.timer and self.timer.elapsed_time > 2:
label = "%s (%s)" % (label, self.timer.rounded)
self.stream.write("%s %s %s ..\r" % (ANSI_ERASE_LINE, state, label))
self.counter += 1
def sleep(self):
"""
Sleep for a short period before redrawing the spinner.
This method is useful when you know you're dealing with code that will
call :func:`step()` at a high frequency. It will sleep for the interval
with which the spinner is redrawn (less than a second). This avoids
creating the equivalent of a busy loop that's rate limiting the
spinner 99% of the time.
This method doesn't redraw the spinner, you still have to call
:func:`step()` in order to do that.
"""
time.sleep(MINIMUM_INTERVAL)
def clear(self):
"""
Clear the spinner.
The next line which is shown on the standard output or error stream
after calling this method will overwrite the line that used to show the
spinner.
"""
if self.interactive:
self.stream.write(ANSI_ERASE_LINE)
def __enter__(self):
"""
Enable the use of spinners as context managers.
:returns: The :class:`Spinner` object.
"""
return self
def __exit__(self, exc_type=None, exc_value=None, traceback=None):
"""Clear the spinner when leaving the context."""
self.clear()
class AutomaticSpinner(object):
"""
Show a spinner on the terminal that automatically starts animating.
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 :keyword:`with` statement. The animation
continues for as long as the context is active.
:class:`AutomaticSpinner` provides an alternative to :class:`Spinner`
for situations where it is not practical for the caller to periodically
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 :mod:`multiprocessing` module by spawning a
subprocess to render the spinner while the main process is busy doing
something more useful. By using the :keyword:`with` statement you're
guaranteed that the subprocess is properly terminated at the appropriate
time.
"""
def __init__(self, label, show_time=True):
"""
Initialize an automatic spinner.
:param label: The label for the spinner (a string).
:param show_time: If this is :data:`True` (the default) then the spinner
shows elapsed time.
"""
self.label = label
self.show_time = show_time
self.shutdown_event = multiprocessing.Event()
self.subprocess = multiprocessing.Process(target=self._target)
def __enter__(self):
"""Enable the use of automatic spinners as context managers."""
self.subprocess.start()
def __exit__(self, exc_type=None, exc_value=None, traceback=None):
"""Enable the use of automatic spinners as context managers."""
self.shutdown_event.set()
self.subprocess.join()
def _target(self):
try:
timer = Timer() if self.show_time else None
with Spinner(label=self.label, timer=timer) as spinner:
while not self.shutdown_event.is_set():
spinner.step()
spinner.sleep()
except KeyboardInterrupt:
# Swallow Control-C signals without producing a nasty traceback that
# won't make any sense to the average user.
pass

669
venv/lib/python3.12/site-packages/humanfriendly/testing.py Normal file
View File

@@ -0,0 +1,669 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: March 6, 2020
# URL: https://humanfriendly.readthedocs.io
"""
Utility classes and functions that make it easy to write :mod:`unittest` compatible test suites.
Over the years I've developed the habit of writing test suites for Python
projects using the :mod:`unittest` module. During those years I've come to know
:pypi:`pytest` and in fact I use :pypi:`pytest` to run my test suites (due to
its much better error reporting) but I've yet to publish a test suite that
*requires* :pypi:`pytest`. I have several reasons for doing so:
- It's nice to keep my test suites as simple and accessible as possible and
not requiring a specific test runner is part of that attitude.
- Whereas :mod:`unittest` is quite explicit, :pypi:`pytest` contains a lot of
magic, which kind of contradicts the Python mantra "explicit is better than
implicit" (IMHO).
"""
# Standard library module
import functools
import logging
import os
import pipes
import shutil
import sys
import tempfile
import time
import unittest
# Modules included in our package.
from humanfriendly.compat import StringIO
from humanfriendly.text import random_string
# Initialize a logger for this module.
logger = logging.getLogger(__name__)
# A unique object reference used to detect missing attributes.
NOTHING = object()
# Public identifiers that require documentation.
__all__ = (
'CallableTimedOut',
'CaptureBuffer',
'CaptureOutput',
'ContextManager',
'CustomSearchPath',
'MockedProgram',
'PatchedAttribute',
'PatchedItem',
'TemporaryDirectory',
'TestCase',
'configure_logging',
'make_dirs',
'retry',
'run_cli',
'skip_on_raise',
'touch',
)
def configure_logging(log_level=logging.DEBUG):
"""configure_logging(log_level=logging.DEBUG)
Automatically configure logging to the terminal.
:param log_level: The log verbosity (a number, defaults
to :mod:`logging.DEBUG <logging>`).
When :mod:`coloredlogs` is installed :func:`coloredlogs.install()` will be
used to configure logging to the terminal. When this fails with an
:exc:`~exceptions.ImportError` then :func:`logging.basicConfig()` is used
as a fall back.
"""
try:
import coloredlogs
coloredlogs.install(level=log_level)
except ImportError:
logging.basicConfig(
level=log_level,
format='%(asctime)s %(name)s[%(process)d] %(levelname)s %(message)s',
datefmt='%Y-%m-%d %H:%M:%S')
def make_dirs(pathname):
"""
Create missing directories.
:param pathname: The pathname of a directory (a string).
"""
if not os.path.isdir(pathname):
os.makedirs(pathname)
def retry(func, timeout=60, exc_type=AssertionError):
"""retry(func, timeout=60, exc_type=AssertionError)
Retry a function until assertions no longer fail.
:param func: A callable. When the callable returns
:data:`False` it will also be retried.
:param timeout: The number of seconds after which to abort (a number,
defaults to 60).
:param exc_type: The type of exceptions to retry (defaults
to :exc:`~exceptions.AssertionError`).
:returns: The value returned by `func`.
:raises: Once the timeout has expired :func:`retry()` will raise the
previously retried assertion error. When `func` keeps returning
:data:`False` until `timeout` expires :exc:`CallableTimedOut`
will be raised.
This function sleeps between retries to avoid claiming CPU cycles we don't
need. It starts by sleeping for 0.1 second but adjusts this to one second
as the number of retries grows.
"""
pause = 0.1
timeout += time.time()
while True:
try:
result = func()
if result is not False:
return result
except exc_type:
if time.time() > timeout:
raise
else:
if time.time() > timeout:
raise CallableTimedOut()
time.sleep(pause)
if pause < 1:
pause *= 2
def run_cli(entry_point, *arguments, **options):
"""
Test a command line entry point.
:param entry_point: The function that implements the command line interface
(a callable).
:param arguments: Any positional arguments (strings) become the command
line arguments (:data:`sys.argv` items 1-N).
:param options: The following keyword arguments are supported:
**capture**
Whether to use :class:`CaptureOutput`. Defaults
to :data:`True` but can be disabled by passing
:data:`False` instead.
**input**
Refer to :class:`CaptureOutput`.
**merged**
Refer to :class:`CaptureOutput`.
**program_name**
Used to set :data:`sys.argv` item 0.
:returns: A tuple with two values:
1. The return code (an integer).
2. The captured output (a string).
"""
# Add the `program_name' option to the arguments.
arguments = list(arguments)
arguments.insert(0, options.pop('program_name', sys.executable))
# Log the command line arguments (and the fact that we're about to call the
# command line entry point function).
logger.debug("Calling command line entry point with arguments: %s", arguments)
# Prepare to capture the return code and output even if the command line
# interface raises an exception (whether the exception type is SystemExit
# or something else).
returncode = 0
stdout = None
stderr = None
try:
# Temporarily override sys.argv.
with PatchedAttribute(sys, 'argv', arguments):
# Manipulate the standard input/output/error streams?
options['enabled'] = options.pop('capture', True)
with CaptureOutput(**options) as capturer:
try:
# Call the command line interface.
entry_point()
finally:
# Get the output even if an exception is raised.
stdout = capturer.stdout.getvalue()
stderr = capturer.stderr.getvalue()
# Reconfigure logging to the terminal because it is very
# likely that the entry point function has changed the
# configured log level.
configure_logging()
except BaseException as e:
if isinstance(e, SystemExit):
logger.debug("Intercepting return code %s from SystemExit exception.", e.code)
returncode = e.code
else:
logger.warning("Defaulting return code to 1 due to raised exception.", exc_info=True)
returncode = 1
else:
logger.debug("Command line entry point returned successfully!")
# Always log the output captured on stdout/stderr, to make it easier to
# diagnose test failures (but avoid duplicate logging when merged=True).
is_merged = options.get('merged', False)
merged_streams = [('merged streams', stdout)]
separate_streams = [('stdout', stdout), ('stderr', stderr)]
streams = merged_streams if is_merged else separate_streams
for name, value in streams:
if value:
logger.debug("Output on %s:\n%s", name, value)
else:
logger.debug("No output on %s.", name)
return returncode, stdout
def skip_on_raise(*exc_types):
"""
Decorate a test function to translation specific exception types to :exc:`unittest.SkipTest`.
:param exc_types: One or more positional arguments give the exception
types to be translated to :exc:`unittest.SkipTest`.
:returns: A decorator function specialized to `exc_types`.
"""
def decorator(function):
@functools.wraps(function)
def wrapper(*args, **kw):
try:
return function(*args, **kw)
except exc_types as e:
logger.debug("Translating exception to unittest.SkipTest ..", exc_info=True)
raise unittest.SkipTest("skipping test because %s was raised" % type(e))
return wrapper
return decorator
def touch(filename):
"""
The equivalent of the UNIX :man:`touch` program in Python.
:param filename: The pathname of the file to touch (a string).
Note that missing directories are automatically created using
:func:`make_dirs()`.
"""
make_dirs(os.path.dirname(filename))
with open(filename, 'a'):
os.utime(filename, None)
class CallableTimedOut(Exception):
"""Raised by :func:`retry()` when the timeout expires."""
class ContextManager(object):
"""Base class to enable composition of context managers."""
def __enter__(self):
"""Enable use as context managers."""
return self
def __exit__(self, exc_type=None, exc_value=None, traceback=None):
"""Enable use as context managers."""
class PatchedAttribute(ContextManager):
"""Context manager that temporary replaces an object attribute using :func:`setattr()`."""
def __init__(self, obj, name, value):
"""
Initialize a :class:`PatchedAttribute` object.
:param obj: The object to patch.
:param name: An attribute name.
:param value: The value to set.
"""
self.object_to_patch = obj
self.attribute_to_patch = name
self.patched_value = value
self.original_value = NOTHING
def __enter__(self):
"""
Replace (patch) the attribute.
:returns: The object whose attribute was patched.
"""
# Enable composition of context managers.
super(PatchedAttribute, self).__enter__()
# Patch the object's attribute.
self.original_value = getattr(self.object_to_patch, self.attribute_to_patch, NOTHING)
setattr(self.object_to_patch, self.attribute_to_patch, self.patched_value)
return self.object_to_patch
def __exit__(self, exc_type=None, exc_value=None, traceback=None):
"""Restore the attribute to its original value."""
# Enable composition of context managers.
super(PatchedAttribute, self).__exit__(exc_type, exc_value, traceback)
# Restore the object's attribute.
if self.original_value is NOTHING:
delattr(self.object_to_patch, self.attribute_to_patch)
else:
setattr(self.object_to_patch, self.attribute_to_patch, self.original_value)
class PatchedItem(ContextManager):
"""Context manager that temporary replaces an object item using :meth:`~object.__setitem__()`."""
def __init__(self, obj, item, value):
"""
Initialize a :class:`PatchedItem` object.
:param obj: The object to patch.
:param item: The item to patch.
:param value: The value to set.
"""
self.object_to_patch = obj
self.item_to_patch = item
self.patched_value = value
self.original_value = NOTHING
def __enter__(self):
"""
Replace (patch) the item.
:returns: The object whose item was patched.
"""
# Enable composition of context managers.
super(PatchedItem, self).__enter__()
# Patch the object's item.
try:
self.original_value = self.object_to_patch[self.item_to_patch]
except KeyError:
self.original_value = NOTHING
self.object_to_patch[self.item_to_patch] = self.patched_value
return self.object_to_patch
def __exit__(self, exc_type=None, exc_value=None, traceback=None):
"""Restore the item to its original value."""
# Enable composition of context managers.
super(PatchedItem, self).__exit__(exc_type, exc_value, traceback)
# Restore the object's item.
if self.original_value is NOTHING:
del self.object_to_patch[self.item_to_patch]
else:
self.object_to_patch[self.item_to_patch] = self.original_value
class TemporaryDirectory(ContextManager):
"""
Easy temporary directory creation & cleanup using the :keyword:`with` statement.
Here's an example of how to use this:
.. code-block:: python
with TemporaryDirectory() as directory:
# Do something useful here.
assert os.path.isdir(directory)
"""
def __init__(self, **options):
"""
Initialize a :class:`TemporaryDirectory` object.
:param options: Any keyword arguments are passed on to
:func:`tempfile.mkdtemp()`.
"""
self.mkdtemp_options = options
self.temporary_directory = None
def __enter__(self):
"""
Create the temporary directory using :func:`tempfile.mkdtemp()`.
:returns: The pathname of the directory (a string).
"""
# Enable composition of context managers.
super(TemporaryDirectory, self).__enter__()
# Create the temporary directory.
self.temporary_directory = tempfile.mkdtemp(**self.mkdtemp_options)
return self.temporary_directory
def __exit__(self, exc_type=None, exc_value=None, traceback=None):
"""Cleanup the temporary directory using :func:`shutil.rmtree()`."""
# Enable composition of context managers.
super(TemporaryDirectory, self).__exit__(exc_type, exc_value, traceback)
# Cleanup the temporary directory.
if self.temporary_directory is not None:
shutil.rmtree(self.temporary_directory)
self.temporary_directory = None
class MockedHomeDirectory(PatchedItem, TemporaryDirectory):
"""
Context manager to temporarily change ``$HOME`` (the current user's profile directory).
This class is a composition of the :class:`PatchedItem` and
:class:`TemporaryDirectory` context managers.
"""
def __init__(self):
"""Initialize a :class:`MockedHomeDirectory` object."""
PatchedItem.__init__(self, os.environ, 'HOME', os.environ.get('HOME'))
TemporaryDirectory.__init__(self)
def __enter__(self):
"""
Activate the custom ``$PATH``.
:returns: The pathname of the directory that has
been added to ``$PATH`` (a string).
"""
# Get the temporary directory.
directory = TemporaryDirectory.__enter__(self)
# Override the value to patch now that we have
# the pathname of the temporary directory.
self.patched_value = directory
# Temporary patch $HOME.
PatchedItem.__enter__(self)
# Pass the pathname of the temporary directory to the caller.
return directory
def __exit__(self, exc_type=None, exc_value=None, traceback=None):
"""Deactivate the custom ``$HOME``."""
super(MockedHomeDirectory, self).__exit__(exc_type, exc_value, traceback)
class CustomSearchPath(PatchedItem, TemporaryDirectory):
"""
Context manager to temporarily customize ``$PATH`` (the executable search path).
This class is a composition of the :class:`PatchedItem` and
:class:`TemporaryDirectory` context managers.
"""
def __init__(self, isolated=False):
"""
Initialize a :class:`CustomSearchPath` object.
:param isolated: :data:`True` to clear the original search path,
:data:`False` to add the temporary directory to the
start of the search path.
"""
# Initialize our own instance variables.
self.isolated_search_path = isolated
# Selectively initialize our superclasses.
PatchedItem.__init__(self, os.environ, 'PATH', self.current_search_path)
TemporaryDirectory.__init__(self)
def __enter__(self):
"""
Activate the custom ``$PATH``.
:returns: The pathname of the directory that has
been added to ``$PATH`` (a string).
"""
# Get the temporary directory.
directory = TemporaryDirectory.__enter__(self)
# Override the value to patch now that we have
# the pathname of the temporary directory.
self.patched_value = (
directory if self.isolated_search_path
else os.pathsep.join([directory] + self.current_search_path.split(os.pathsep))
)
# Temporary patch the $PATH.
PatchedItem.__enter__(self)
# Pass the pathname of the temporary directory to the caller
# because they may want to `install' custom executables.
return directory
def __exit__(self, exc_type=None, exc_value=None, traceback=None):
"""Deactivate the custom ``$PATH``."""
super(CustomSearchPath, self).__exit__(exc_type, exc_value, traceback)
@property
def current_search_path(self):
"""The value of ``$PATH`` or :data:`os.defpath` (a string)."""
return os.environ.get('PATH', os.defpath)
class MockedProgram(CustomSearchPath):
"""
Context manager to mock the existence of a program (executable).
This class extends the functionality of :class:`CustomSearchPath`.
"""
def __init__(self, name, returncode=0, script=None):
"""
Initialize a :class:`MockedProgram` object.
:param name: The name of the program (a string).
:param returncode: The return code that the program should emit (a
number, defaults to zero).
:param script: Shell script code to include in the mocked program (a
string or :data:`None`). This can be used to mock a
program that is expected to generate specific output.
"""
# Initialize our own instance variables.
self.program_name = name
self.program_returncode = returncode
self.program_script = script
self.program_signal_file = None
# Initialize our superclasses.
super(MockedProgram, self).__init__()
def __enter__(self):
"""
Create the mock program.
:returns: The pathname of the directory that has
been added to ``$PATH`` (a string).
"""
directory = super(MockedProgram, self).__enter__()
self.program_signal_file = os.path.join(directory, 'program-was-run-%s' % random_string(10))
pathname = os.path.join(directory, self.program_name)
with open(pathname, 'w') as handle:
handle.write('#!/bin/sh\n')
handle.write('echo > %s\n' % pipes.quote(self.program_signal_file))
if self.program_script:
handle.write('%s\n' % self.program_script.strip())
handle.write('exit %i\n' % self.program_returncode)
os.chmod(pathname, 0o755)
return directory
def __exit__(self, *args, **kw):
"""
Ensure that the mock program was run.
:raises: :exc:`~exceptions.AssertionError` when
the mock program hasn't been run.
"""
try:
assert self.program_signal_file and os.path.isfile(self.program_signal_file), \
("It looks like %r was never run!" % self.program_name)
finally:
return super(MockedProgram, self).__exit__(*args, **kw)
class CaptureOutput(ContextManager):
"""
Context manager that captures what's written to :data:`sys.stdout` and :data:`sys.stderr`.
.. attribute:: stdin
The :class:`~humanfriendly.compat.StringIO` object used to feed the standard input stream.
.. attribute:: stdout
The :class:`CaptureBuffer` object used to capture the standard output stream.
.. attribute:: stderr
The :class:`CaptureBuffer` object used to capture the standard error stream.
"""
def __init__(self, merged=False, input='', enabled=True):
"""
Initialize a :class:`CaptureOutput` object.
:param merged: :data:`True` to merge the streams,
:data:`False` to capture them separately.
:param input: The data that reads from :data:`sys.stdin`
should return (a string).
:param enabled: :data:`True` to enable capturing (the default),
:data:`False` otherwise. This makes it easy to
unconditionally use :class:`CaptureOutput` in
a :keyword:`with` block while preserving the
choice to opt out of capturing output.
"""
self.stdin = StringIO(input)
self.stdout = CaptureBuffer()
self.stderr = self.stdout if merged else CaptureBuffer()
self.patched_attributes = []
if enabled:
self.patched_attributes.extend(
PatchedAttribute(sys, name, getattr(self, name))
for name in ('stdin', 'stdout', 'stderr')
)
def __enter__(self):
"""Start capturing what's written to :data:`sys.stdout` and :data:`sys.stderr`."""
super(CaptureOutput, self).__enter__()
for context in self.patched_attributes:
context.__enter__()
return self
def __exit__(self, exc_type=None, exc_value=None, traceback=None):
"""Stop capturing what's written to :data:`sys.stdout` and :data:`sys.stderr`."""
super(CaptureOutput, self).__exit__(exc_type, exc_value, traceback)
for context in self.patched_attributes:
context.__exit__(exc_type, exc_value, traceback)
def get_lines(self):
"""Get the contents of :attr:`stdout` split into separate lines."""
return self.get_text().splitlines()
def get_text(self):
"""Get the contents of :attr:`stdout` as a Unicode string."""
return self.stdout.get_text()
def getvalue(self):
"""Get the text written to :data:`sys.stdout`."""
return self.stdout.getvalue()
class CaptureBuffer(StringIO):
"""
Helper for :class:`CaptureOutput` to provide an easy to use API.
The two methods defined by this subclass were specifically chosen to match
the names of the methods provided by my :pypi:`capturer` package which
serves a similar role as :class:`CaptureOutput` but knows how to simulate
an interactive terminal (tty).
"""
def get_lines(self):
"""Get the contents of the buffer split into separate lines."""
return self.get_text().splitlines()
def get_text(self):
"""Get the contents of the buffer as a Unicode string."""
return self.getvalue()
class TestCase(unittest.TestCase):
"""Subclass of :class:`unittest.TestCase` with automatic logging and other miscellaneous features."""
def __init__(self, *args, **kw):
"""
Initialize a :class:`TestCase` object.
Any positional and/or keyword arguments are passed on to the
initializer of the superclass.
"""
super(TestCase, self).__init__(*args, **kw)
def setUp(self, log_level=logging.DEBUG):
"""setUp(log_level=logging.DEBUG)
Automatically configure logging to the terminal.
:param log_level: Refer to :func:`configure_logging()`.
The :func:`setUp()` method is automatically called by
:class:`unittest.TestCase` before each test method starts.
It does two things:
- Logging to the terminal is configured using
:func:`configure_logging()`.
- Before the test method starts a newline is emitted, to separate the
name of the test method (which will be printed to the terminal by
:mod:`unittest` or :pypi:`pytest`) from the first line of logging
output that the test method is likely going to generate.
"""
# Configure logging to the terminal.
configure_logging(log_level)
# Separate the name of the test method (printed by the superclass
# and/or py.test without a newline at the end) from the first line of
# logging output that the test method is likely going to generate.
sys.stderr.write("\n")

1495
venv/lib/python3.12/site-packages/humanfriendly/tests.py Normal file
View File

File diff suppressed because it is too large Load Diff

449
venv/lib/python3.12/site-packages/humanfriendly/text.py Normal file
View File

@@ -0,0 +1,449 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: December 1, 2020
# URL: https://humanfriendly.readthedocs.io
"""
Simple text manipulation functions.
The :mod:`~humanfriendly.text` module contains simple functions to manipulate text:
- The :func:`concatenate()` and :func:`pluralize()` functions make it easy to
generate human friendly output.
- The :func:`format()`, :func:`compact()` and :func:`dedent()` functions
provide a clean and simple to use syntax for composing large text fragments
with interpolated variables.
- The :func:`tokenize()` function parses simple user input.
"""
# Standard library modules.
import numbers
import random
import re
import string
import textwrap
# Public identifiers that require documentation.
__all__ = (
'compact',
'compact_empty_lines',
'concatenate',
'dedent',
'format',
'generate_slug',
'is_empty_line',
'join_lines',
'pluralize',
'pluralize_raw',
'random_string',
'split',
'split_paragraphs',
'tokenize',
'trim_empty_lines',
)
def compact(text, *args, **kw):
'''
Compact whitespace in a string.
Trims leading and trailing whitespace, replaces runs of whitespace
characters with a single space and interpolates any arguments using
:func:`format()`.
:param text: The text to compact (a string).
:param args: Any positional arguments are interpolated using :func:`format()`.
:param kw: Any keyword arguments are interpolated using :func:`format()`.
:returns: The compacted text (a string).
Here's an example of how I like to use the :func:`compact()` function, this
is an example from a random unrelated project I'm working on at the moment::
raise PortDiscoveryError(compact("""
Failed to discover port(s) that Apache is listening on!
Maybe I'm parsing the wrong configuration file? ({filename})
""", filename=self.ports_config))
The combination of :func:`compact()` and Python's multi line strings allows
me to write long text fragments with interpolated variables that are easy
to write, easy to read and work well with Python's whitespace
sensitivity.
'''
non_whitespace_tokens = text.split()
compacted_text = ' '.join(non_whitespace_tokens)
return format(compacted_text, *args, **kw)
def compact_empty_lines(text):
"""
Replace repeating empty lines with a single empty line (similar to ``cat -s``).
:param text: The text in which to compact empty lines (a string).
:returns: The text with empty lines compacted (a string).
"""
i = 0
lines = text.splitlines(True)
while i < len(lines):
if i > 0 and is_empty_line(lines[i - 1]) and is_empty_line(lines[i]):
lines.pop(i)
else:
i += 1
return ''.join(lines)
def concatenate(items, conjunction='and', serial_comma=False):
"""
Concatenate a list of items in a human friendly way.
:param items:
A sequence of strings.
:param conjunction:
The word to use before the last item (a string, defaults to "and").
:param serial_comma:
:data:`True` to use a `serial comma`_, :data:`False` otherwise
(defaults to :data:`False`).
:returns:
A single string.
>>> from humanfriendly.text import concatenate
>>> concatenate(["eggs", "milk", "bread"])
'eggs, milk and bread'
.. _serial comma: https://en.wikipedia.org/wiki/Serial_comma
"""
items = list(items)
if len(items) > 1:
final_item = items.pop()
formatted = ', '.join(items)
if serial_comma:
formatted += ','
return ' '.join([formatted, conjunction, final_item])
elif items:
return items[0]
else:
return ''
def dedent(text, *args, **kw):
"""
Dedent a string (remove common leading whitespace from all lines).
Removes common leading whitespace from all lines in the string using
:func:`textwrap.dedent()`, removes leading and trailing empty lines using
:func:`trim_empty_lines()` and interpolates any arguments using
:func:`format()`.
:param text: The text to dedent (a string).
:param args: Any positional arguments are interpolated using :func:`format()`.
:param kw: Any keyword arguments are interpolated using :func:`format()`.
:returns: The dedented text (a string).
The :func:`compact()` function's documentation contains an example of how I
like to use the :func:`compact()` and :func:`dedent()` functions. The main
difference is that I use :func:`compact()` for text that will be presented
to the user (where whitespace is not so significant) and :func:`dedent()`
for data file and code generation tasks (where newlines and indentation are
very significant).
"""
dedented_text = textwrap.dedent(text)
trimmed_text = trim_empty_lines(dedented_text)
return format(trimmed_text, *args, **kw)
def format(text, *args, **kw):
"""
Format a string using the string formatting operator and/or :meth:`str.format()`.
:param text: The text to format (a string).
:param args: Any positional arguments are interpolated into the text using
the string formatting operator (``%``). If no positional
arguments are given no interpolation is done.
:param kw: Any keyword arguments are interpolated into the text using the
:meth:`str.format()` function. If no keyword arguments are given
no interpolation is done.
:returns: The text with any positional and/or keyword arguments
interpolated (a string).
The implementation of this function is so trivial that it seems silly to
even bother writing and documenting it. Justifying this requires some
context :-).
**Why format() instead of the string formatting operator?**
For really simple string interpolation Python's string formatting operator
is ideal, but it does have some strange quirks:
- When you switch from interpolating a single value to interpolating
multiple values you have to wrap them in tuple syntax. Because
:func:`format()` takes a `variable number of arguments`_ it always
receives a tuple (which saves me a context switch :-). Here's an
example:
>>> from humanfriendly.text import format
>>> # The string formatting operator.
>>> print('the magic number is %s' % 42)
the magic number is 42
>>> print('the magic numbers are %s and %s' % (12, 42))
the magic numbers are 12 and 42
>>> # The format() function.
>>> print(format('the magic number is %s', 42))
the magic number is 42
>>> print(format('the magic numbers are %s and %s', 12, 42))
the magic numbers are 12 and 42
- When you interpolate a single value and someone accidentally passes in a
tuple your code raises a :exc:`~exceptions.TypeError`. Because
:func:`format()` takes a `variable number of arguments`_ it always
receives a tuple so this can never happen. Here's an example:
>>> # How expecting to interpolate a single value can fail.
>>> value = (12, 42)
>>> print('the magic value is %s' % value)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: not all arguments converted during string formatting
>>> # The following line works as intended, no surprises here!
>>> print(format('the magic value is %s', value))
the magic value is (12, 42)
**Why format() instead of the str.format() method?**
When you're doing complex string interpolation the :meth:`str.format()`
function results in more readable code, however I frequently find myself
adding parentheses to force evaluation order. The :func:`format()` function
avoids this because of the relative priority between the comma and dot
operators. Here's an example:
>>> "{adjective} example" + " " + "(can't think of anything less {adjective})".format(adjective='silly')
"{adjective} example (can't think of anything less silly)"
>>> ("{adjective} example" + " " + "(can't think of anything less {adjective})").format(adjective='silly')
"silly example (can't think of anything less silly)"
>>> format("{adjective} example" + " " + "(can't think of anything less {adjective})", adjective='silly')
"silly example (can't think of anything less silly)"
The :func:`compact()` and :func:`dedent()` functions are wrappers that
combine :func:`format()` with whitespace manipulation to make it easy to
write nice to read Python code.
.. _variable number of arguments: https://docs.python.org/2/tutorial/controlflow.html#arbitrary-argument-lists
"""
if args:
text %= args
if kw:
text = text.format(**kw)
return text
def generate_slug(text, delimiter="-"):
"""
Convert text to a normalized "slug" without whitespace.
:param text: The original text, for example ``Some Random Text!``.
:param delimiter: The delimiter used to separate words
(defaults to the ``-`` character).
:returns: The slug text, for example ``some-random-text``.
:raises: :exc:`~exceptions.ValueError` when the provided
text is nonempty but results in an empty slug.
"""
slug = text.lower()
escaped = delimiter.replace("\\", "\\\\")
slug = re.sub("[^a-z0-9]+", escaped, slug)
slug = slug.strip(delimiter)
if text and not slug:
msg = "The provided text %r results in an empty slug!"
raise ValueError(format(msg, text))
return slug
def is_empty_line(text):
"""
Check if a text is empty or contains only whitespace.
:param text: The text to check for "emptiness" (a string).
:returns: :data:`True` if the text is empty or contains only whitespace,
:data:`False` otherwise.
"""
return len(text) == 0 or text.isspace()
def join_lines(text):
"""
Remove "hard wrapping" from the paragraphs in a string.
:param text: The text to reformat (a string).
:returns: The text without hard wrapping (a string).
This function works by removing line breaks when the last character before
a line break and the first character after the line break are both
non-whitespace characters. This means that common leading indentation will
break :func:`join_lines()` (in that case you can use :func:`dedent()`
before calling :func:`join_lines()`).
"""
return re.sub(r'(\S)\n(\S)', r'\1 \2', text)
def pluralize(count, singular, plural=None):
"""
Combine a count with the singular or plural form of a word.
:param count: The count (a number).
:param singular: The singular form of the word (a string).
:param plural: The plural form of the word (a string or :data:`None`).
:returns: The count and singular or plural word concatenated (a string).
See :func:`pluralize_raw()` for the logic underneath :func:`pluralize()`.
"""
return '%s %s' % (count, pluralize_raw(count, singular, plural))
def pluralize_raw(count, singular, plural=None):
"""
Select the singular or plural form of a word based on a count.
:param count: The count (a number).
:param singular: The singular form of the word (a string).
:param plural: The plural form of the word (a string or :data:`None`).
:returns: The singular or plural form of the word (a string).
When the given count is exactly 1.0 the singular form of the word is
selected, in all other cases the plural form of the word is selected.
If the plural form of the word is not provided it is obtained by
concatenating the singular form of the word with the letter "s". Of course
this will not always be correct, which is why you have the option to
specify both forms.
"""
if not plural:
plural = singular + 's'
return singular if float(count) == 1.0 else plural
def random_string(length=(25, 100), characters=string.ascii_letters):
"""random_string(length=(25, 100), characters=string.ascii_letters)
Generate a random string.
:param length: The length of the string to be generated (a number or a
tuple with two numbers). If this is a tuple then a random
number between the two numbers given in the tuple is used.
:param characters: The characters to be used (a string, defaults
to :data:`string.ascii_letters`).
:returns: A random string.
The :func:`random_string()` function is very useful in test suites; by the
time I included it in :mod:`humanfriendly.text` I had already included
variants of this function in seven different test suites :-).
"""
if not isinstance(length, numbers.Number):
length = random.randint(length[0], length[1])
return ''.join(random.choice(characters) for _ in range(length))
def split(text, delimiter=','):
"""
Split a comma-separated list of strings.
:param text: The text to split (a string).
:param delimiter: The delimiter to split on (a string).
:returns: A list of zero or more nonempty strings.
Here's the default behavior of Python's built in :meth:`str.split()`
function:
>>> 'foo,bar, baz,'.split(',')
['foo', 'bar', ' baz', '']
In contrast here's the default behavior of the :func:`split()` function:
>>> from humanfriendly.text import split
>>> split('foo,bar, baz,')
['foo', 'bar', 'baz']
Here is an example that parses a nested data structure (a mapping of
logging level names to one or more styles per level) that's encoded in a
string so it can be set as an environment variable:
>>> from pprint import pprint
>>> encoded_data = 'debug=green;warning=yellow;error=red;critical=red,bold'
>>> parsed_data = dict((k, split(v, ',')) for k, v in (split(kv, '=') for kv in split(encoded_data, ';')))
>>> pprint(parsed_data)
{'debug': ['green'],
'warning': ['yellow'],
'error': ['red'],
'critical': ['red', 'bold']}
"""
return [token.strip() for token in text.split(delimiter) if token and not token.isspace()]
def split_paragraphs(text):
"""
Split a string into paragraphs (one or more lines delimited by an empty line).
:param text: The text to split into paragraphs (a string).
:returns: A list of strings.
"""
paragraphs = []
for chunk in text.split('\n\n'):
chunk = trim_empty_lines(chunk)
if chunk and not chunk.isspace():
paragraphs.append(chunk)
return paragraphs
def tokenize(text):
"""
Tokenize a text into numbers and strings.
:param text: The text to tokenize (a string).
:returns: A list of strings and/or numbers.
This function is used to implement robust tokenization of user input in
functions like :func:`.parse_size()` and :func:`.parse_timespan()`. It
automatically coerces integer and floating point numbers, ignores
whitespace and knows how to separate numbers from strings even without
whitespace. Some examples to make this more concrete:
>>> from humanfriendly.text import tokenize
>>> tokenize('42')
[42]
>>> tokenize('42MB')
[42, 'MB']
>>> tokenize('42.5MB')
[42.5, 'MB']
>>> tokenize('42.5 MB')
[42.5, 'MB']
"""
tokenized_input = []
for token in re.split(r'(\d+(?:\.\d+)?)', text):
token = token.strip()
if re.match(r'\d+\.\d+', token):
tokenized_input.append(float(token))
elif token.isdigit():
tokenized_input.append(int(token))
elif token:
tokenized_input.append(token)
return tokenized_input
def trim_empty_lines(text):
"""
Trim leading and trailing empty lines from the given text.
:param text: The text to trim (a string).
:returns: The trimmed text (a string).
"""
lines = text.splitlines(True)
while lines and is_empty_line(lines[0]):
lines.pop(0)
while lines and is_empty_line(lines[-1]):
lines.pop(-1)
return ''.join(lines)

351
venv/lib/python3.12/site-packages/humanfriendly/usage.py Normal file
View File

@@ -0,0 +1,351 @@
# Human friendly input/output in Python.
#
# Author: Peter Odding <peter@peterodding.com>
# Last Change: June 11, 2021
# URL: https://humanfriendly.readthedocs.io
"""
Parsing and reformatting of usage messages.
The :mod:`~humanfriendly.usage` module parses and reformats usage messages:
- The :func:`format_usage()` function takes a usage message and inserts ANSI
escape sequences that highlight items of special significance like command
line options, meta variables, etc. The resulting usage message is (intended
to be) easier to read on a terminal.
- The :func:`render_usage()` function takes a usage message and rewrites it to
reStructuredText_ suitable for inclusion in the documentation of a Python
package. This provides a DRY solution to keeping a single authoritative
definition of the usage message while making it easily available in
documentation. As a cherry on the cake it's not just a pre-formatted dump of
the usage message but a nicely formatted reStructuredText_ fragment.
- The remaining functions in this module support the two functions above.
Usage messages in general are free format of course, however the functions in
this module assume a certain structure from usage messages in order to
successfully parse and reformat them, refer to :func:`parse_usage()` for
details.
.. _DRY: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
.. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText
"""
# Standard library modules.
import csv
import functools
import logging
import re
# Standard library module or external dependency (see setup.py).
from importlib import import_module
# Modules included in our package.
from humanfriendly.compat import StringIO
from humanfriendly.text import dedent, split_paragraphs, trim_empty_lines
# Public identifiers that require documentation.
__all__ = (
'find_meta_variables',
'format_usage',
'import_module', # previously exported (backwards compatibility)
'inject_usage',
'parse_usage',
'render_usage',
'USAGE_MARKER',
)
USAGE_MARKER = "Usage:"
"""The string that starts the first line of a usage message."""
START_OF_OPTIONS_MARKER = "Supported options:"
"""The string that marks the start of the documented command line options."""
# Compiled regular expression used to tokenize usage messages.
USAGE_PATTERN = re.compile(r'''
# Make sure whatever we're matching isn't preceded by a non-whitespace
# character.
(?<!\S)
(
# A short command line option or a long command line option
# (possibly including a meta variable for a value).
(-\w|--\w+(-\w+)*(=\S+)?)
# Or ...
|
# An environment variable.
\$[A-Za-z_][A-Za-z0-9_]*
# Or ...
|
# Might be a meta variable (usage() will figure it out).
[A-Z][A-Z0-9_]+
)
''', re.VERBOSE)
# Compiled regular expression used to recognize options.
OPTION_PATTERN = re.compile(r'^(-\w|--\w+(-\w+)*(=\S+)?)$')
# Initialize a logger for this module.
logger = logging.getLogger(__name__)
def format_usage(usage_text):
"""
Highlight special items in a usage message.
:param usage_text: The usage message to process (a string).
:returns: The usage message with special items highlighted.
This function highlights the following special items:
- The initial line of the form "Usage: ..."
- Short and long command line options
- Environment variables
- Meta variables (see :func:`find_meta_variables()`)
All items are highlighted in the color defined by
:data:`.HIGHLIGHT_COLOR`.
"""
# Ugly workaround to avoid circular import errors due to interdependencies
# between the humanfriendly.terminal and humanfriendly.usage modules.
from humanfriendly.terminal import ansi_wrap, HIGHLIGHT_COLOR
formatted_lines = []
meta_variables = find_meta_variables(usage_text)
for line in usage_text.strip().splitlines(True):
if line.startswith(USAGE_MARKER):
# Highlight the "Usage: ..." line in bold font and color.
formatted_lines.append(ansi_wrap(line, color=HIGHLIGHT_COLOR))
else:
# Highlight options, meta variables and environment variables.
formatted_lines.append(replace_special_tokens(
line, meta_variables,
lambda token: ansi_wrap(token, color=HIGHLIGHT_COLOR),
))
return ''.join(formatted_lines)
def find_meta_variables(usage_text):
"""
Find the meta variables in the given usage message.
:param usage_text: The usage message to parse (a string).
:returns: A list of strings with any meta variables found in the usage
message.
When a command line option requires an argument, the convention is to
format such options as ``--option=ARG``. The text ``ARG`` in this example
is the meta variable.
"""
meta_variables = set()
for match in USAGE_PATTERN.finditer(usage_text):
token = match.group(0)
if token.startswith('-'):
option, _, value = token.partition('=')
if value:
meta_variables.add(value)
return list(meta_variables)
def parse_usage(text):
"""
Parse a usage message by inferring its structure (and making some assumptions :-).
:param text: The usage message to parse (a string).
:returns: A tuple of two lists:
1. A list of strings with the paragraphs of the usage message's
"introduction" (the paragraphs before the documentation of the
supported command line options).
2. A list of strings with pairs of command line options and their
descriptions: Item zero is a line listing a supported command
line option, item one is the description of that command line
option, item two is a line listing another supported command
line option, etc.
Usage messages in general are free format of course, however
:func:`parse_usage()` assume a certain structure from usage messages in
order to successfully parse them:
- The usage message starts with a line ``Usage: ...`` that shows a symbolic
representation of the way the program is to be invoked.
- After some free form text a line ``Supported options:`` (surrounded by
empty lines) precedes the documentation of the supported command line
options.
- The command line options are documented as follows::
-v, --verbose
Make more noise.
So all of the variants of the command line option are shown together on a
separate line, followed by one or more paragraphs describing the option.
- There are several other minor assumptions, but to be honest I'm not sure if
anyone other than me is ever going to use this functionality, so for now I
won't list every intricate detail :-).
If you're curious anyway, refer to the usage message of the `humanfriendly`
package (defined in the :mod:`humanfriendly.cli` module) and compare it with
the usage message you see when you run ``humanfriendly --help`` and the
generated usage message embedded in the readme.
Feel free to request more detailed documentation if you're interested in
using the :mod:`humanfriendly.usage` module outside of the little ecosystem
of Python packages that I have been building over the past years.
"""
introduction = []
documented_options = []
# Split the raw usage message into paragraphs.
paragraphs = split_paragraphs(text)
# Get the paragraphs that are part of the introduction.
while paragraphs:
# Check whether we've found the end of the introduction.
end_of_intro = (paragraphs[0] == START_OF_OPTIONS_MARKER)
# Append the current paragraph to the introduction.
introduction.append(paragraphs.pop(0))
# Stop after we've processed the complete introduction.
if end_of_intro:
break
logger.debug("Parsed introduction: %s", introduction)
# Parse the paragraphs that document command line options.
while paragraphs:
documented_options.append(dedent(paragraphs.pop(0)))
description = []
while paragraphs:
# Check if the next paragraph starts the documentation of another
# command line option. We split on a comma followed by a space so
# that our parsing doesn't trip up when the label used for an
# option's value contains commas.
tokens = [t.strip() for t in re.split(r',\s', paragraphs[0]) if t and not t.isspace()]
if all(OPTION_PATTERN.match(t) for t in tokens):
break
else:
description.append(paragraphs.pop(0))
# Join the description's paragraphs back together so we can remove
# common leading indentation.
documented_options.append(dedent('\n\n'.join(description)))
logger.debug("Parsed options: %s", documented_options)
return introduction, documented_options
def render_usage(text):
"""
Reformat a command line program's usage message to reStructuredText_.
:param text: The plain text usage message (a string).
:returns: The usage message rendered to reStructuredText_ (a string).
"""
meta_variables = find_meta_variables(text)
introduction, options = parse_usage(text)
output = [render_paragraph(p, meta_variables) for p in introduction]
if options:
output.append('\n'.join([
'.. csv-table::',
' :header: Option, Description',
' :widths: 30, 70',
'',
]))
csv_buffer = StringIO()
csv_writer = csv.writer(csv_buffer)
while options:
variants = options.pop(0)
description = options.pop(0)
csv_writer.writerow([
render_paragraph(variants, meta_variables),
('\n\n'.join(render_paragraph(p, meta_variables) for p in split_paragraphs(description))).rstrip(),
])
csv_lines = csv_buffer.getvalue().splitlines()
output.append('\n'.join(' %s' % line for line in csv_lines))
logger.debug("Rendered output: %s", output)
return '\n\n'.join(trim_empty_lines(o) for o in output)
def inject_usage(module_name):
"""
Use cog_ to inject a usage message into a reStructuredText_ file.
:param module_name: The name of the module whose ``__doc__`` attribute is
the source of the usage message (a string).
This simple wrapper around :func:`render_usage()` makes it very easy to
inject a reformatted usage message into your documentation using cog_. To
use it you add a fragment like the following to your ``*.rst`` file::
.. [[[cog
.. from humanfriendly.usage import inject_usage
.. inject_usage('humanfriendly.cli')
.. ]]]
.. [[[end]]]
The lines in the fragment above are single line reStructuredText_ comments
that are not copied to the output. Their purpose is to instruct cog_ where
to inject the reformatted usage message. Once you've added these lines to
your ``*.rst`` file, updating the rendered usage message becomes really
simple thanks to cog_:
.. code-block:: sh
$ cog.py -r README.rst
This will inject or replace the rendered usage message in your
``README.rst`` file with an up to date copy.
.. _cog: http://nedbatchelder.com/code/cog/
"""
import cog
usage_text = import_module(module_name).__doc__
cog.out("\n" + render_usage(usage_text) + "\n\n")
def render_paragraph(paragraph, meta_variables):
# Reformat the "Usage:" line to highlight "Usage:" in bold and show the
# remainder of the line as pre-formatted text.
if paragraph.startswith(USAGE_MARKER):
tokens = paragraph.split()
return "**%s** `%s`" % (tokens[0], ' '.join(tokens[1:]))
# Reformat the "Supported options:" line to highlight it in bold.
if paragraph == 'Supported options:':
return "**%s**" % paragraph
# Reformat shell transcripts into code blocks.
if re.match(r'^\s*\$\s+\S', paragraph):
# Split the paragraph into lines.
lines = paragraph.splitlines()
# Check if the paragraph is already indented.
if not paragraph[0].isspace():
# If the paragraph isn't already indented we'll indent it now.
lines = [' %s' % line for line in lines]
lines.insert(0, '.. code-block:: sh')
lines.insert(1, '')
return "\n".join(lines)
# The following reformatting applies only to paragraphs which are not
# indented. Yes this is a hack - for now we assume that indented paragraphs
# are code blocks, even though this assumption can be wrong.
if not paragraph[0].isspace():
# Change UNIX style `quoting' so it doesn't trip up DocUtils.
paragraph = re.sub("`(.+?)'", r'"\1"', paragraph)
# Escape asterisks.
paragraph = paragraph.replace('*', r'\*')
# Reformat inline tokens.
paragraph = replace_special_tokens(
paragraph, meta_variables,
lambda token: '``%s``' % token,
)
return paragraph
def replace_special_tokens(text, meta_variables, replace_fn):
return USAGE_PATTERN.sub(functools.partial(
replace_tokens_callback,
meta_variables=meta_variables,
replace_fn=replace_fn
), text)
def replace_tokens_callback(match, meta_variables, replace_fn):
token = match.group(0)
if not (re.match('^[A-Z][A-Z0-9_]+$', token) and token not in meta_variables):
token = replace_fn(token)
return token