Feat #89 isolation and extensibility design #92

BrutalSimplicity · 2022-10-23T22:43:42Z

This is a large PR, and for that I apologize. I'm happy to make changes and provide additional explanation based on feedback.

The main focus of this PR is to add support for isolating Rich Click's formatting and help configuration. The design supports isolation of these components by:

Extending Click's HelpFormatter class
Creating a HelpConfiguration class that doubles the current module-level settings
Adding a decorator that allows the HelpConfiguration to be passed into Click via the supported context_settings argument provided by the Command and Group classes.

Since this package does have an established user base I attempted to maintain the module-level settings behavior to prevent any breaking changes. I also added some tests to help verify the test suite using pytest and pytest-cov for test coverage. The tests are the bulk of this change as I used a snapshot-based approach to capture the input and output of the examples, and then validate their compatibility between module-level and context-level configuration.

I got it a bit carried away and added a few other nuggets since they seemed closely related.

The Rich Console object can also be configured per command and is distinct from the Console instance used internally by the formatter. The RichHelpFormatter creates a console based on the RichHelpConfiguration as the tight coupling between the Formatter and Click's internals make it difficult to allow the Console to be configured externally (i.e. one example is that Click expects help formatting to be buffered).
RichContext class was created to allow creation of the custom formatter.
The Rich Command, Group, and Context now expose the Console and RichHelpConfiguration properties. I thought this might make sense, but happy to remove if it might cause problems elsewhere.
Added contributor vscode settings

See ewels#88 ewels#89

… formatting - Adhere to click `HelpFormatter` interface - Add tests :D See ewels#89 ewels#88 ewels#25 ewels#19

…tures` directory

…examples

This reverts commit 78d137e.

BrutalSimplicity · 2022-10-25T09:30:53Z

The rich-codex workflow updated the images, but seems like the screen grabs are no longer generating colorful output for some of the commands. Not quite sure what to make of it. Maybe some leaky module config state carrying over across snapshots? When I run rich-codex or the rich-click examples I always seem to get some unsupported characters in my terminal.

This reverts commit 8d50c17.

The `command.get_usage` method generates the usage string by writing it to a new formatter. This caused Rich to apply the styles twice.

.vscode/settings.json

ewels · 2022-10-25T12:06:22Z

This is amazing, thanks so much! A tonne of stuff to go through so it may take me a few days to find time to properly look at it, but on the face of it I think it looks great 🚀

ewels · 2022-10-25T12:08:23Z

Note - rich-codex running on: [push] is nice in principle but in practice I've been finding it super spammy on other projects. So feel free to switch it to just workflow_dispatch: if you like. Can then try to remember to run it before release.

…t colorful svgs

BrutalSimplicity · 2022-10-28T01:24:23Z

Yea, I hear you on the rich-codex workflow.

I made a fix to handle the issue I found with improper usage formatting. It looks like internally click creates a new formatter to print out the usage string, so the Rich formatting was being applied twice. Now, instead of asking click for the usage I changed that portion to call write_usage on the formatter and that seemed fix the behavior.

Other than that, I believe (please verify) that any other changes were only updates to configuration attributes and threading the formatter through to other functions.

Perhaps, it might be worth looking at moving that functionality into the formatter itself, but the PR is large enough as is, and I didn't want to accidentally break the internals.

BrutalSimplicity · 2022-10-28T01:29:44Z

src/rich_click/rich_command.py


    def main(self, *args, standalone_mode: bool = True, **kwargs):
+        formatter = self._formatter = RichHelpFormatter(config=self.help_config)


Not sure the formatter is worth exposing here. It's only needed in the exception handling at this point as the formatter used for help generation is created by click internally. I only exposed it as a possible convenience for users. Maybe the Rich console is enough.

BrutalSimplicity · 2022-10-28T01:41:02Z

src/rich_click/rich_click.py

-        r"(?P<metavar>\<[^\>]+\>)",
-        r"(?P<usage>Usage: )",
-    ]
+def _get_rich_formatter(formatter: Optional[click.HelpFormatter] = None) -> RichHelpFormatter:


This is possibly not needed since the formatter entry points are in the public functions. But, I was a bit unsure of other ways users may be using the "private-by-convention" functions in this module.

My thought was maybe someone is calling these internal functions to supplement behavior, and are calling them without the newly added formatter argument. In that case, this should fall back to the original behavior since it will then resolve the formatter from the active click context or the module-level configuration.

ewels · 2022-11-14T11:51:07Z

Hi @BrutalSimplicity,

Sorry for being slow on the review here. If I'm honest, much of what you've written is a bit beyond me 😅 I'm keen to merge, but it makes me nervous about maintaining the code if I don't really understand it. What do you think about being added as a collaborator on the repo to help out more long term? Then I would feel much happier to merge even though I'm out of my depth.

General points:

Screenshots in the PR are still lacking colour, even if fixed in the workflow. Can probably just do a bit of rebasing to remove those commits? I've switched to workflow_dispatch outside of this PR already.
Would be great to add some more docs / examples if we're adding new extensibility here.

Cheers,

Phil

ewels · 2023-03-28T12:55:01Z

Merging into a new branch so that I can continue on the final bits to get this merged 👍🏻

BrutalSimplicity and others added 12 commits October 23, 2022 09:27

chore: ewels#25 add unit test using rich click examples

a594c1e

feat: move module attribute settings into class

1eef5ed

See ewels#88 ewels#89

feat: Add support for isolated configuration of Rich Console and help…

85a5ed6

… formatting - Adhere to click `HelpFormatter` interface - Add tests :D See ewels#89 ewels#88 ewels#25 ewels#19

chore: add test coverage and github actions test workflow

6f5035a

Generate new screengrabs with rich-codex

2458e04

chore: set rich configuration defaults to make tests more reproducible

0cae120

chore: also set force_terminal setting for reproducible test results

6a30fb1

chore: fix up pre-commit mypy regex to exclude files under `tests/fix…

e96e7d8

…tures` directory

chore: add use_pty flag to rich codex to generate proper codex image …

78d137e

…examples

chore: revert auto-committed updates to docs in images

981b53f

This reverts commit 78d137e.

chore: re-run all workflows with rich-codex enabled

4ccf470

Generate new screengrabs with rich-codex

8d50c17

BrutalSimplicity added 4 commits October 25, 2022 05:14

Revert "Generate new screengrabs with rich-codex"

e6bb045

This reverts commit 8d50c17.

fix: fixes usage formatting

63cd4b5

The `command.get_usage` method generates the usage string by writing it to a new formatter. This caused Rich to apply the styles twice.

chore: update tests

afe138c

fix: make StringIO buffer appear like a tty device if stdout says so

67e30dd

ewels reviewed Oct 25, 2022

View reviewed changes

.vscode/settings.json Show resolved Hide resolved

Generate new screengrabs with rich-codex

325d267

chore: add some force environment variables to make rich-codex prin…

c0af814

…t colorful svgs

BrutalSimplicity commented Oct 28, 2022

View reviewed changes

ewels changed the base branch from main to pr-92 March 28, 2023 12:54

ewels changed the base branch from pr-92 to pullrequest-92 March 28, 2023 12:56

ewels merged commit 7a6f61b into ewels:pullrequest-92 Mar 28, 2023

ewels mentioned this pull request Mar 28, 2023

Feat #89 isolation and extensibility design #103

Merged

ewels mentioned this pull request Apr 12, 2023

Added echo, echo_via_pager #29

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feat #89 isolation and extensibility design #92

Feat #89 isolation and extensibility design #92

BrutalSimplicity commented Oct 23, 2022

BrutalSimplicity commented Oct 25, 2022

ewels commented Oct 25, 2022

ewels commented Oct 25, 2022

BrutalSimplicity commented Oct 28, 2022

BrutalSimplicity Oct 28, 2022

BrutalSimplicity Oct 28, 2022

ewels commented Nov 14, 2022

ewels commented Mar 28, 2023


		def main(self, args, standalone_mode: bool = True, *kwargs):
		formatter = self._formatter = RichHelpFormatter(config=self.help_config)

Feat #89 isolation and extensibility design #92

Feat #89 isolation and extensibility design #92

Conversation

BrutalSimplicity commented Oct 23, 2022

BrutalSimplicity commented Oct 25, 2022

ewels commented Oct 25, 2022

ewels commented Oct 25, 2022

BrutalSimplicity commented Oct 28, 2022

BrutalSimplicity Oct 28, 2022

Choose a reason for hiding this comment

BrutalSimplicity Oct 28, 2022

Choose a reason for hiding this comment

ewels commented Nov 14, 2022

ewels commented Mar 28, 2023