The previous commit already ensures that the interactive help for
individual commands is sent to a pager. This does the same for the
'help' command with no arguments.

Change-Id: If5e38421d21e09f88a572dbb508b1997381bdb87

Using the autopage library we can automatically send the help output to
a pager (less, by default), git-style. The pager is configured to not
reset the terminal on exit, avoiding the problem when piping to less
manually that the help text you want to refer to disappears off the
screen when you go to use it. The pager is only invoked when the output
is to the terminal.

Since we invoke the pager, we can ensure that it is correctly set up to
interpret ANSI escape codes, so it is safe to use colour to make the
output easier to read. The autopage library provides light styling of
the default argparse help output, and some additional colour
highlighting is added here for the command list (which is generated by
cliff, not using argparse's formatting code).

Change-Id: If9e1aa5166da32c58cc0fa617f4f81eaa9b2c470
Depends-On: https://review.opendev.org/c/openstack/requirements/+/799343

Fedora is already testing Python 3.10 [1] and an issue
has been raised [2].
All the details are in the BZ ticket but TLDR is that
"optional arguments" was replaced with "options [3].
So, I used assertRegexp to accept both of them (i.e
"optional arguments" and "options").

[1] https://fedoraproject.org/wiki/Changes/Python3.10
[2] https://bugzilla.redhat.com/show_bug.cgi?id=1914138
[3] https://github.com/python/cpython/commit/fb35fa49d192368e94ffec09c092260ed0fea2e1

Change-Id: I18d9f1bea7bb5a7afb273550314c36da7b466a69

If we are piping output to a command that exits before the entire
output is written (e.g. "head") then we will receive a BrokenPipeError.
This is expected and we should react by exiting gracefully, setting an
appropriate return code (128 + SIGPIPE).

Change-Id: I0d60e44450da1f48dbd8f459549da80fda69aad5

Adding conflict_handler as attribut in the Command class in order to be
able to take control of this parameter and change to different behavior
that argparse is handling: error / resolve / ignore.

Callers will be able to override it and get a proper Parser object.

Change-Id: I327ece99a04bc8b2ebfa554dea643b1f2a456336

Setuptools v54.1.0 introduces a warning that the use of
dash-separated options in 'setup.cfg' will not be supported
in a future version [1].
Get ahead of the issue by replacing the dashes with underscores.
Without this, we see 'UserWarning' messages
like the following on new enough
versions of setuptools:

  UserWarning: Usage of dash-separated 'description-file' will not be
  supported in future versions. Please use the underscore name
  'description_file' instead

[1] https://github.com/pypa/setuptools/commit/a2e9ae4cb

Change-Id: Icccc9cc2b3a0d236746c4b58a8815d25d8b0a443

inspect.getargspec() is deprecated since py3

[1] https://docs.python.org/3/library/inspect.html#inspect.getargspec

Change-Id: I7a1692d9979e9ffaf781de1f39f5bfa59a01cf3c

Moving on py3 as the default runtime for tox to avoid to update this at
each new cycle.

Wallaby support officially the following runtimes [1]:
- Python 3.6
- Python 3.8

During Victoria Python 3.7 was used as the default runtime [2] however this
version isn't longer officially supported.

[1] https://governance.openstack.org/tc/reference/runtimes/wallaby.html#python-runtimes-for-wallaby
[2] https://governance.openstack.org/tc/reference/runtimes/victoria.html#python-runtimes-for-victoria

Change-Id: I5d419e881a42e627fd0699cb2ab68b66e7295cee

This is an automatically generated patch to ensure unit testing
is in place for all the of the tested runtimes for xena.

See also the PTI in governance [1].

[1]: https://governance.openstack.org/tc/reference/project-testing-interface.html

Change-Id: Id810ebcb6620b4f6235ef3d616b858b4ab6b18b4

PrettyTable was capped at a < 0.8, which meant we were getting the
veritably ancient 0.7.2 release first release in April 2013 (!) [1].
The project is now being maintained as a Jazzband project [2], meaning
we should switch to this new version.

The only significant change required here is that we no longer set the
'min_width' attribute since that actually does something - the wrong
thing - now. We want this attribute to set a lower bound on the wrap
width as opposed to an absolute minimum we can use, which is what
setting the 'min_width' attribute would do.

While we're here, we also remove a now useless bit of Python 2 code and
bump cmd2 to a slightly newer version.

[1] https://pypi.org/project/prettytable/#history
[2] https://github.com/jazzband/prettytable



Change-Id: Iceac729e7a9429e8ab25c60524a48d0aaeebeb37
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Depends-On: https://review.opendev.org/c/openstack/requirements/+/774917

Allow users to reverse sorting direction.

Change-Id: Iecd539139c5a7ce4abaaee2ff5632a2459437d51
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

Implement the '__lt__' magic method, thus providing the minimal set of
rich comparison methods necessary to support sorting. This will allows
users using these formatters for the more basic types (i.e. not dicts)
to sort their output using the standard '--sort-column' option.

Change-Id: I08e1f1bc75fa6452f19dfb9d221c1daec194d58d
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

One unfortunate change (or fortunate, depending on how you look at
types) in Python 3 is the inability to sort iterables of different
types. For example:

  >>> x = ['foo', 'bar', None, 'qux']
  >>> sorted(x)
  Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
  TypeError: '<' not supported between instances of 'NoneType' and 'str'

Fortunately, we can take advantage of the fact that by providing a
function for the 'key' that returns a tuple, we can sort on multiple
conditions. In this case, "when the first key returns that two elements
are equal, the second key is used to compare." [1] We can use this to
first separate the values by whether they are None or not, punting those
that are not to the end, before sorting the non-None values normally.
For example:

  >>> x = ['foo', 'bar', None, 'qux']
  >>> sorted(x, key=lambda k: (k is None, k))
  ['bar', 'foo', 'qux', None]

We were already using this feature implicitly through our use of
'operator.itemgetter(*indexes)', which will return a tuple if there is
more than one item in 'indexes', and now we simply make that explicit,
fixing the case where we're attempting to compare a comparable type
with None. For all other cases, such as comparing a value that isn't
comparable, we surround things with a try-catch and a debug logging
statement to allow things to continue.

Note that we could optimize what we're done further by building a key
value that covers all indexes, rather than using a for loop to do so.
For example:

  >>> x = [('baz', 2), (None, 0), ('bar', 3), ('baz', 4), ('qux', 0)]
  >>> sorted(x, key=lambda k: list(
  ...     itertools.chain((k[i] is None, k[i]) for i in (0, 1)))
  ... )
  [('bar', 3), ('baz', 2), ('baz', 4), ('qux', 0), (None, 0)]

However, this would be harder to grok and would also mean we're unable
to handle exceptions on a single column where e.g. there are mixed types
or types that are not comparable while still sorting on the other
columns. Perhaps this would be desirable for some users, but sorting on
a best-effort basis does seem wiser and generally more user friendly.
Anyone that wants to sort on such columns should ensure their types are
comparable or implement their own sorting implementation.

[1] https://www.kite.com/python/answers/how-to-sort-by-two-keys-in-python



Change-Id: I4803051a6dd05c143a15923254af97e32cd39693
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Story: 2008456
Task: 41466

Change-Id: I040fccd1714dccd7a87aaf10d397ad3a3ef476d3

Change-Id: I27a3689c2e22452c082764eed8d26cd8f3bbcd13
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

This is not part of the PTI and is currently broken. While discussions
are ongoing about removing it from every project, there's a definite
lean towards doing so. Let's do just that. We can re-add in the future
if necessary.

While we're here, we fix some indentation in 'tox.ini'.

Change-Id: Ib4784d9da96d05a54acdfbb3744af0cb053c0c6c
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

There were some in both the docs and the demo application.

Change-Id: I58d14cd3a372f9bdf617cbfbcb5ce34169ac83f8
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

Currently, comparing instances of this fails:

  >>> from cliff.columns import FormattableColumn
  >>> class Test(FormattableColumn):
  ...     def human_readable(self):
  ...         return str(self._data)
  ...
  >>> data = {'x': 'y'}
  >>> x = Test(data)
  >>> y = Test(data)
  >>> x == y
  False

Clearly it should not. Resolve this by implementing a custom comparison.

Change-Id: I4b96475ca6a689f4055dc5ea34b82b3867a65555
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Story: #2008320
Task: #41218

Update the URL to the upper-constraints file to point to the redirect
rule on releases.openstack.org so will switch to the correct
upper-constraints list automatically when the requirements repository branches.

Change-Id: Ia69a02b539230e65e25da65d5d76a9f650490256

Replace the following items with Python 3 style code.

- six.moves
- six.PY2
- six.PY3
- six.string_types
- six.text_type

Change-Id: I1656b976864c8f2343e658a4abf432d30c151d0b

We also need to change the lower-constraint requirements to make them
py3.8 compatible. See https://bugs.launchpad.net/nova/+bug/1886298

Change-Id: Id06963dfdb20074cb9d8f0f2416a8e0937006059

cliff now uses storyboard as the bug tracker, but the documents
have not been updated.

Change-Id: Ie2ceda088f708dee2d6dd0877087e9a5c27e928f

With the advent of importlib, entry points are no long a setuptools-only
thing. Update the docs to reflect that.

Change-Id: I099f397ddb4d71879597cfe67ef2a1eff4a8d1af
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

Change-Id: I76f87914149dc845ec53ec6a64342ca59f7dc4dc

This can be removed because it's no longer a transitive dependency of oslo.i18n.

Change-Id: I2dabd2eea6d589952ecabf203f3c0d075672799f