Enchanced formatter; additional TOML config

Author: dakrauth

README.rst

@@ -51,8 +51,8 @@ a GeoNames ID of 5128581. Pass that to the ``--alias`` option along with another
 you would like to use::
 
     $ when --db --alias 5128581 NYC
-    $ when NYC
-    2023-03-26 05:24:02-0400 (America/New_York) 085d12w (New York City, US, New York) [🌒 Waxing Crescent]
+    $ when --source NYC
+    2023-07-06 07:58:33-0400 (EDT, America/New_York) 187d27w (New York City, New York, US)[🌕 Full Moon]
 
 
 Example
@@ -61,24 +61,24 @@ Example
 .. code:: bash
 
     $ when
-    2023-02-11 17:43:44+0900 (KST) 042d06w  [🌖 Waning Gibbous]
+    2023-07-06 20:58:02+0900 (KST, Asia/Seoul) 187d27w [🌕 Full Moon]
 
     $ when --source CST
-    2023-02-11 02:44:22-0600 (Central Standard Time) 042d06w  [🌖 Waning Gibbous]
-    2023-02-11 12:44:22+0400 (Caucasus Standard Time) 042d06w  [🌖 Waning Gibbous]
-    2023-02-11 16:44:22+0800 (China Standard Time) 042d06w  [🌖 Waning Gibbous]
-    2023-02-11 03:44:22-0500 (Cuba Standard Time) 042d06w  [🌖 Waning Gibbous]
+    2023-07-06 06:58:54-0500 (CDT, Central Standard Time) 187d27w [🌕 Full Moon]
+    2023-07-06 15:58:54+0400 (+04, Caucasus Standard Time) 187d27w [🌕 Full Moon]
+    2023-07-06 19:58:54+0800 (CST, China Standard Time) 187d27w [🌕 Full Moon]
+    2023-07-06 07:58:54-0400 (CDT, Cuba Standard Time) 187d27w [🌕 Full Moon]
 
     $ when --source Paris
-    2023-02-11 09:45:11+0100 (Europe/Paris) 042d06w  (Villeparisis, FR, Île-de-France) [🌖 Waning Gibbous]
-    2023-02-11 09:45:11+0100 (Europe/Paris) 042d06w  (Paris, FR, Île-de-France) [🌖 Waning Gibbous]
-    2023-02-11 09:45:11+0100 (Europe/Paris) 042d06w  (Cormeilles-en-Parisis, FR, Île-de-France) [🌖 Waning Gibbous]
-    2023-02-11 03:45:11-0500 (America/Port-au-Prince) 042d06w  (Fond Parisien, HT, Ouest) [🌖 Waning Gibbous]
-    2023-02-11 02:45:11-0600 (America/Chicago) 042d06w  (Paris, US, Texas) [🌖 Waning Gibbous]
+    2023-07-06 13:59:25+0200 (CEST, Europe/Paris) 187d27w (Villeparisis, Île-de-France, FR)[🌕 Full Moon]
+    2023-07-06 13:59:25+0200 (CEST, Europe/Paris) 187d27w (Paris, Île-de-France, FR)[🌕 Full Moon]
+    2023-07-06 13:59:25+0200 (CEST, Europe/Paris) 187d27w (Cormeilles-en-Parisis, Île-de-France, FR)[🌕 Full Moon]
+    2023-07-06 07:59:25-0400 (EDT, America/Port-au-Prince) 187d27w (Fond Parisien, Ouest, HT)[🌕 Full Moon]
+    2023-07-06 06:59:25-0500 (CDT, America/Chicago) 187d27w (Paris, Texas, US)[🌕 Full Moon]
 
     $ when --source "San Francisco,US" --target America/New_York Mar 7 1945 7:00pm
-    1945-03-07 22:00:00-0400 (America/New_York) 066d10w  [🌘 Waning Crescent]
-    1945-03-07 22:00:00-0400 (America/New_York) 066d10w  [🌘 Waning Crescent]
+    1945-03-07 22:00:00-0400 (EWT, America/New_York) 066d10w [🌘 Waning Crescent]
+    1945-03-07 22:00:00-0400 (EWT, America/New_York) 066d10w [🌘 Waning Crescent]
 
 
 Develop

pyproject.toml

@@ -0,0 +1,2 @@
+[tool.black]
+line-length = 100

setup.py

@@ -27,7 +27,11 @@
     package_dir={"": "src"},
     include_package_data=True,
     entry_points={"console_scripts": ["when = when.__main__:main",]},
-    install_requires=["python-dateutil>=2.8.0", "toml>=0.10.2", "requests"],
+    install_requires=[
+        "python-dateutil>=2.8.0",
+        "toml>=0.10.2",
+        "requests",
+    ],
     classifiers=[
         "Environment :: Console",
         "Intended Audience :: Developers",

src/when/__init__.py

@@ -1,8 +1,8 @@
 """
-Calculate and convert times across time zones.
+Calculate and convert times across time zones and cities of significant population.
 """
 
-__version__ = (2, 1, 0)
+__version__ = (3, 0, 0)
 VERSION = ".".join(str(i) for i in __version__)
 
 

src/when/cli.py

@@ -1,11 +1,13 @@
 #!/usr/bin/env python
+import sys
 import logging
 import argparse
 
 from . import core
 from . import VERSION
 from . import utils
 from .db import make
+from .config import settings, __doc__ as FORMAT_HELP
 
 logger = logging.getLogger(__name__)
 
@@ -29,14 +31,15 @@ def db_main(args, db):
 
 
 def config_main(args):
-    print(core.settings.write_text())
+    print(settings.write_text())
     return 0
 
 
 def get_parser():
     parser = argparse.ArgumentParser(
         description="Convert times to and from time zones or cities",
         formatter_class=argparse.RawDescriptionHelpFormatter,
+        add_help=False,
     )
 
     parser.add_argument(
@@ -46,6 +49,14 @@ def get_parser():
         help="Timestamp to parse, defaults to local time",
     )
 
+    parser.add_argument(
+        "-h",
+        "--help",
+        action="store_true",
+        default=False,
+        help="Show helpful usage information",
+    )
+
     parser.add_argument(
         "-s",
         "--source",
@@ -65,17 +76,12 @@ def get_parser():
         """,
     )
 
+    default_format = settings["formats"]["named"]["default"]
     parser.add_argument(
         "-f",
         "--format",
-        default=core.DEFAULT_FORMAT,
-        help="""
-            Output formatting. Additionaly predefined formats by name are {}.
-            Default: {}, where %%K is timezone long name
-        """.format(
-            ", ".join(["rfc2822, iso, "]),
-            core.DEFAULT_FORMAT.replace("%", "%%"),
-        ),
+        default=default_format,
+        help="Output formatting. Additional formats can be shown using the -v option with -h",
     )
 
     parser.add_argument(
@@ -88,7 +94,11 @@ def get_parser():
     parser.add_argument("--holidays", help="Show holidays for given country code.")
 
     parser.add_argument(
-        "-v", "--verbosity", action="count", default=0, help="Verbosity (-v, -vv, etc)"
+        "-v",
+        "--verbosity",
+        action="count",
+        default=0,
+        help="Verbosity (-v, -vv, etc). Use -v to show `when` extension detailed help",
     )
 
     parser.add_argument(
@@ -152,15 +162,16 @@ def log_config(verbosity):
         log_level = logging.DEBUG if verbosity > 1 else logging.INFO
 
     logging.basicConfig(level=log_level, format=log_format, force=True)
-    logger.debug("Configuration files read: %s", ", ".join(core.settings.read_from))
+    logger.debug("Configuration files read: %s", ", ".join(settings.read_from))
 
 
 def main(sys_args, when=None):
     debug = "--pdb" in sys_args
     if debug:
         sys_args.remove("--pdb")
 
-    args = get_parser().parse_args(sys_args)
+    parser = get_parser()
+    args = parser.parse_args(sys_args)
 
     if debug:
         try:
@@ -170,15 +181,21 @@ def main(sys_args, when=None):
         pdb.set_trace()
 
     log_config(args.verbosity)
+    if args.help:
+        parser.print_help()
+        if args.verbosity:
+            print(FORMAT_HELP)
+        else:
+            print("\nUse -v option for details\n")
+        sys.exit(0)
+
     when = when or core.When()
     if args.db:
         return db_main(args, when.db)
     elif args.config:
         return config_main(args)
     elif args.holidays:
-        return core.holidays(
-            args.holidays, args.timestamp[0] if args.timestamp else None
-        )
+        return core.holidays(args.holidays, args.timestamp[0] if args.timestamp else None)
 
     ts = utils.parse_source_input(args.timestamp)
     targets = args.target