diff options
author | Nguyễn Gia Phong <cnx@loang.net> | 2025-06-15 21:53:53 +0900 |
---|---|---|
committer | Nguyễn Gia Phong <cnx@loang.net> | 2025-06-15 21:53:53 +0900 |
commit | c3d356c8b80659468a0a7429636a128c156509ae (patch) | |
tree | 8d7af71b623e1cfb360ee935f809411059e0ca76 /src | |
parent | 637e73f023107c142c1eecc187c18a5581c10794 (diff) | |
download | scadere-c3d356c8b80659468a0a7429636a128c156509ae.tar.gz |
Add examples to help and man pages
Diffstat (limited to 'src')
-rw-r--r-- | src/scadere/__init__.py | 34 | ||||
-rw-r--r-- | src/scadere/check.py | 21 | ||||
-rw-r--r-- | src/scadere/listen.py | 34 |
3 files changed, 73 insertions, 16 deletions
diff --git a/src/scadere/__init__.py b/src/scadere/__init__.py index ada0f29..f2b41bd 100644 --- a/src/scadere/__init__.py +++ b/src/scadere/__init__.py @@ -18,10 +18,15 @@ from argparse import HelpFormatter, ONE_OR_MORE -__all__ = ['__version__', 'GNUHelpFormatter', 'NetLoc'] +__all__ = ['__version__', 'GNUHelpFormatter', 'NetLoc', 'format_examples'] __version__ = '0.1.0' +EXAMPLE_PREFIX = ' ' * 2 +# help2man's implementation detail +EXAMPLE_DESCRIPTION_PREFIX = ' ' * 20 + + class GNUHelpFormatter(HelpFormatter): """Help formatter for ArgumentParser following GNU Coding Standards.""" @@ -33,6 +38,24 @@ class GNUHelpFormatter(HelpFormatter): """Substitute 'Options:' for 'options:'.""" super().start_section(heading.capitalize()) + def _fill_text(self, text, width, indent): + """Preserve examples' formatting.""" + desc_position = max(len(EXAMPLE_DESCRIPTION_PREFIX), + min(self._action_max_length+2, + self._max_help_position)) + desc_width = width - desc_position + desc_indent = indent + ' '*desc_position + example_indent = indent + EXAMPLE_PREFIX + parts = [] + for line in text.splitlines(): + if line.startswith(EXAMPLE_DESCRIPTION_PREFIX): + parts.append(super()._fill_text(line, desc_width, desc_indent)) + elif line.startswith(EXAMPLE_PREFIX): + parts.append(example_indent+line.strip()) + else: # not example + parts.append(super()._fill_text(line, width, indent)) + return '\n'.join(parts) + def _format_args(self, action, default_metavar): """Substitute 'METAVAR...' for 'METAVAR [METAVAR ...]'.""" if action.nargs == ONE_OR_MORE: @@ -67,3 +90,12 @@ class NetLoc: return string, self.default_port hostname, port = string.rsplit(':', 1) return hostname, int(port) # ValueError to be handled by argparse + + +def format_examples(examples): + """Format example commands and their description .""" + lines = ['Examples:'] + for example, description in examples: + lines.append(EXAMPLE_PREFIX+example) + lines.append(EXAMPLE_DESCRIPTION_PREFIX+description) + return '\n'.join(lines) diff --git a/src/scadere/check.py b/src/scadere/check.py index 0937e75..380f71c 100644 --- a/src/scadere/check.py +++ b/src/scadere/check.py @@ -27,7 +27,7 @@ from sys import argv, stderr, stdout from unicodedata import category as unicode_category from uuid import uuid4 -from . import __version__, GNUHelpFormatter, NetLoc +from . import __version__, GNUHelpFormatter, NetLoc, format_examples __all__ = ['main'] @@ -94,12 +94,20 @@ def check(netlocs, after, output, fake_ca=None): base64_from_str(ca), file=output) -def main(arguments=argv[1:]): +def main(prog='scadere-check', arguments=argv[1:]): """Run TLS checker.""" - description = ('Check TLS certificate expiration of HOST,' - ' where PORT defaults to 443.') - parser = ArgumentParser(prog='scadere-check', allow_abbrev=False, - description=description, + desc = ('Check TLS certificate expiration of HOST,' + ' where PORT defaults to 443.\n\n' + 'The output is intended to be used by scadere-listen(1).') + examples = [((f'{prog} --output=/var/lib/scadere/certificates' + ' example.com example.net'), + ('Check if TLS certificates used by example.com:443' + ' and example.net:443 are either invalid' + ' or expiring within the next week,' + ' then write the result to /var/lib/scadere/certificates.'))] + + parser = ArgumentParser(prog=prog, allow_abbrev=False, description=desc, + epilog=format_examples(examples), formatter_class=GNUHelpFormatter) parser.add_argument('-v', '--version', action='version', version=f'%(prog)s {__version__}') @@ -110,6 +118,7 @@ def main(arguments=argv[1:]): parser.add_argument('-o', '--output', metavar='PATH', type=FileType('w'), default=stdout, help='output file (default to stdout)') + args = parser.parse_args(arguments) with args.output: # pragma: no cover after = datetime.now(timezone.utc) + timedelta(days=args.days) diff --git a/src/scadere/listen.py b/src/scadere/listen.py index 649a7cd..2888524 100644 --- a/src/scadere/listen.py +++ b/src/scadere/listen.py @@ -32,7 +32,7 @@ from xml.etree.ElementTree import (Element as xml_element, indent, tostring as string_from_xml) from sys import argv -from . import __version__, GNUHelpFormatter, NetLoc +from . import __version__, GNUHelpFormatter, NetLoc, format_examples from .check import base64_from_str __all__ = ['main'] @@ -312,21 +312,37 @@ def with_trailing_slash(base_url): return base_url if base_url.endswith('/') else f'{base_url}/' -def main(arguments=argv[1:]): +def main(prog='scadere-listen', arguments=argv[1:]): """Launch server.""" - description = ('Serve the TLS certificate expiration feed' - ' from INPUT file for base URL at HOST:PORT,' - ' where HOST defaults to localhost and PORT' - ' is selected randomly if not specified.') - parser = ArgumentParser(prog='scadere-listen', allow_abbrev=False, - description=description, + desc = ('Serve at URL Atom feeds for TLS certificate renewal reminder.' + ' It is possible for clients to filter domains' + ' using one or more "domain" URL queries.\n\n' + 'The certificate information is read from the file at PATH,' + ' which is generated by scadere-check(1).\n\n' + 'The server listens for TCP connections coming to HOST:PORT,' + ' where HOST defaults to localhost' + ' and PORT is selected randomly if not specified.\n\n') + examples = [((f'{prog} /var/lib/scadere/certificates' + ' https://scadere.example/ :4433'), + ('Serve renewal reminder feed using information' + ' from /var/lib/scadere/certificates on localhost:4433,' + ' to be reverse proxied to https://scadere.example/')), + ('https://scadere.example/', + 'Atom feed for all checked TLS certificates'), + ('https://scadere.example/?domain=example.com&domain=net', + ('Atom feed for checked TLS certificates for example.com,' + ' its subdomains, and domains under the TLD NET'))] + + parser = ArgumentParser(prog=prog, allow_abbrev=False, description=desc, + epilog=format_examples(examples), formatter_class=GNUHelpFormatter) parser.add_argument('-v', '--version', action='version', version=f'%(prog)s {__version__}') - parser.add_argument('certs', metavar='INPUT', type=Path) + parser.add_argument('certs', metavar='PATH', type=Path) parser.add_argument('base_url', metavar='URL', type=with_trailing_slash) parser.add_argument('netloc', metavar='[HOST][:PORT]', nargs='?', type=NetLoc(None), default=('localhost', None)) + args = parser.parse_args(arguments) run(listen(args.certs, args.base_url, *args.netloc)) # pragma: no cover |