feat: add usage samples and improve documentation for dotted-path usage

Author: arthur-debert

bin/usage-samples

@@ -0,0 +1,40 @@
+#! /usr/bin/env bash
+
+# Don't exit on error
+set +e
+
+## this files just collects all possible outputs for regular and errors so
+## that we can test the output of the program
+
+# Function to indent each line of input by 4 spaces
+function indent() {
+	sed 's/^/  /'
+}
+
+function run_command() {
+	local description="$2"
+	echo ""
+	echo -e "\033[1m$description: \033[0m"
+	echo ""
+	eval "$1" | indent
+	echo ""
+}
+
+run_command "dotcat" "no arguments, quick usage"
+
+run_command "dotcat --help" "--help"
+
+run_command "dotcat help" "help"
+
+run_command "dotcat pyproject.toml project.authors" "correct usage, both file exists and keys is found"
+
+run_command "dotcat pyproject.toml" "missing dotted-path"
+
+run_command "dotcat project.authors" "missing file"
+
+run_command "dotcat nothere.toml project.authors" "no such file"
+
+run_command "dotcat pyproject.toml project.nothere" "missing dotted-path"
+
+# Reset exit behavior
+set -e

src/dotcat/__init__.py

@@ -1 +1,3 @@
-from .dotcat import run, main
+from .dotcat import run, main, USAGE, HELP
+
+__all__ = ["run", "main", "USAGE", "HELP"]

src/dotcat/dotcat.py

@@ -3,7 +3,7 @@
 This script reads values, including nested values, from structured data files (JSON, YAML, TOML, INI).
 
 Usage:
-    dotcat <file> <dot_separated_key>
+    dotcat <file> <dotted-path>
 
 Example:
     dotcat config.json python.editor.tabSize
@@ -75,14 +75,27 @@ def red(text: str) -> str:
 
 USAGE = f"""
 {bold('dotcat')}
+Read values from structured data files (JSON, YAML, TOML, INI)
+
+  Usage: dotcat <file> <dotted-path>
+
+    <file>          The input file (JSON, YAML, TOML, INI).
+    <dotted-path>   The dotted path to the desired data (e.g., project.authors).
+
+  See `dotcat --help` for more information.
+"""
+
+HELP = f"""
+{bold('dotcat')}
 Read values, including nested values, from structured data files (JSON, YAML, TOML, INI)
 
 {bold('USAGE:')}
-dotcat <file> <dot_separated_key>
+  dotcat <file> <dotted-path>
 
-{bold('EXAMPLE:')}
-dotcat config.json python.editor.tabSize
-dotcat somefile.toml a.b.c
+{bold('EXAMPLES:')}
+  dotcat config.json python.editor.tabSize
+  dotcat somefile.toml a.b.c
+  dotcat package.json dependencies.react
 """
 
 ######################################################################
@@ -299,8 +312,8 @@ def from_attr_chain(data: Dict[str, Any], lookup_chain: str) -> Any:
     Accesses a nested dictionary value with an attribute chain encoded by a dot-separated string.
 
     Args:
-        adict: The dictionary to access.
-        lookup_path: The dot-separated string representing the nested keys.
+        data: The dictionary to access.
+        lookup_chain: The dotted-path string representing the nested keys.
 
     Returns:
         The value at the specified nested key, or None if the key doesn't exist.
@@ -329,26 +342,31 @@ def from_attr_chain(data: Dict[str, Any], lookup_chain: str) -> Any:
 
 def parse_args(args: List[str]) -> Tuple[str, str, str, bool]:
     """
-    Returns the filename, lookup chain, output format, and check_install flag.
+    Returns the filename, dotted-path, output format, and check_install flag.
 
     Args:
         args: The list of command-line arguments.
 
     Returns:
-        The filename, lookup chain, output format, and check_install flag.
+        The filename, dotted-path, output format, and check_install flag.
     """
     # Handle help commands
-    if args is None or len(args) == 0 or args == ["help"] or args == ["--help"]:
-        print(USAGE)
+    if args is None or len(args) == 0:
+        print(HELP)  # Show help for no arguments
+        sys.exit(0)
+
+    # Handle explicit help requests
+    if "help" in args or "-h" in args or "--help" in args:
+        print(HELP)  # Show help for help requests
         sys.exit(0)
 
     parser = argparse.ArgumentParser(add_help=False)
     parser.add_argument("file", type=str, nargs="?", help="The file to read from")
     parser.add_argument(
-        "dot_separated_key",
+        "dotted_path",
         type=str,
         nargs="?",
-        help="The dot-separated key to look up",
+        help="The dotted-path to look up",
     )
     parser.add_argument(
         "--output",
@@ -365,15 +383,15 @@ def parse_args(args: List[str]) -> Tuple[str, str, str, bool]:
     parsed_args = parser.parse_args(args)
     return (
         parsed_args.file,
-        parsed_args.dot_separated_key,
+        parsed_args.dotted_path,
         parsed_args.output,
         parsed_args.check_install,
     )
 
 
 def is_likely_dot_path(arg: str) -> bool:
     """
-    Determines if an argument is likely a dot path rather than a file path.
+    Determines if an argument is likely a dotted-path rather than a file path.
 
     Args:
         arg: The argument to check.
@@ -402,8 +420,8 @@ def run(args: List[str] = None) -> None:
         check_install()
         return
 
-    # Special case: If we have only one argument and it looks like a dot path,
-    # treat it as the dot path rather than the file
+    # Special case: If we have only one argument and it looks like a dotted-path,
+    # treat it as the dotted-path rather than the file
     if filename is not None and lookup_chain is None and len(args) == 1:
         if is_likely_dot_path(filename):
             # Swap the arguments
@@ -414,33 +432,33 @@ def run(args: List[str] = None) -> None:
     # Handle cases where one of the required arguments is missing
     if lookup_chain is None or filename is None:
         if filename is not None and lookup_chain is None:
-            # Case 1: File is provided but dot pattern is missing
+            # Case 1: File is provided but dotted-path is missing
             try:
                 if os.path.exists(filename):
-                    # File exists, but dot pattern is missing
+                    # File exists, but dotted-path is missing
                     print(
-                        f"{red('Dot')} path required. {red('Which')} value do you want me to look up in {filename}?"
+                        f"Dotted-path required. Which value do you want me to look up in {filename}?"
                     )
-                    print(f"\n$dotcat {filename} {red('<pattern>')}")
+                    print(f"\n$dotcat {filename} {red('<dotted-path>')}")
                     sys.exit(2)  # Invalid usage
             except Exception:
                 # If there's any error checking the file, fall back to general usage message
                 pass
         elif filename is None and lookup_chain is not None:
-            # Case 2: Dot pattern is provided but file is missing
-            # Check if the argument looks like a dot path (contains dots)
+            # Case 2: Dotted-path is provided but file is missing
+            # Check if the argument looks like a dotted-path (contains dots)
             if "." in lookup_chain:
-                # It looks like a dot path, so assume the file is missing
+                # It looks like a dotted-path, so assume the file is missing
                 print(
-                    f"{red('File')} path required. {red('Which')} file contains the value at {lookup_chain}?"
+                    f"File path required. Which file contains the value at {lookup_chain}?"
                 )
                 print(f"\n$dotcat {red('<file>')} {lookup_chain}")
                 sys.exit(2)  # Invalid usage
             # Otherwise, it might be a file without an extension or something else,
             # so fall back to the general usage message
 
         # General usage message for other cases
-        print(USAGE)
+        print(USAGE)  # Display usage for invalid arguments
         sys.exit(2)  # Invalid usage
 
     # gets the parsed data

tests/test_exec.py

@@ -1,6 +1,6 @@
 from io import StringIO
 import sys
-from dotcat import run
+from dotcat import run, HELP
 
 import pytest
 
@@ -19,17 +19,7 @@ def test_no_arguments():
     with pytest.raises(SystemExit) as pytest_wrapped_e:
         run(test_args)
     sys.stdout = sys.__stdout__
-    expected_output = """
-dotcat
-Read values, including nested values, from structured data files (JSON, YAML, TOML, INI)
-
-USAGE:
-dotcat <file> <dot_separated_key>
-
-EXAMPLE:
-dotcat config.json python.editor.tabSize
-dotcat somefile.toml a.b.c
-""".strip()
+    expected_output = remove_ansi_escape_sequences(HELP.strip())
     actual_output = remove_ansi_escape_sequences(captured_output.getvalue().strip())
     assert actual_output == expected_output
     assert pytest_wrapped_e.type == SystemExit
@@ -125,9 +115,9 @@ def test_file_without_dot_pattern():
     sys.stdout = sys.__stdout__
     actual_output = remove_ansi_escape_sequences(captured_output.getvalue().strip())
     # Check that the output contains the specific file name and guidance
-    assert "Dot path required" in actual_output
+    assert "Dotted-path required" in actual_output
     assert "tests/fixtures/test.json" in actual_output
-    assert "<pattern>" in actual_output
+    assert "<dotted-path>" in actual_output
     assert pytest_wrapped_e.type == SystemExit
     assert pytest_wrapped_e.value.code == 2
 
@@ -154,17 +144,7 @@ def test_help_command():
     with pytest.raises(SystemExit) as pytest_wrapped_e:
         run(test_args)
     sys.stdout = sys.__stdout__
-    expected_output = """
-dotcat
-Read values, including nested values, from structured data files (JSON, YAML, TOML, INI)
-
-USAGE:
-dotcat <file> <dot_separated_key>
-
-EXAMPLE:
-dotcat config.json python.editor.tabSize
-dotcat somefile.toml a.b.c
-""".strip()
+    expected_output = remove_ansi_escape_sequences(HELP.strip())
     actual_output = remove_ansi_escape_sequences(captured_output.getvalue().strip())
     assert actual_output == expected_output
     assert pytest_wrapped_e.type == SystemExit
@@ -178,17 +158,7 @@ def test_help_flag():
     with pytest.raises(SystemExit) as pytest_wrapped_e:
         run(test_args)
     sys.stdout = sys.__stdout__
-    expected_output = """
-dotcat
-Read values, including nested values, from structured data files (JSON, YAML, TOML, INI)
-
-USAGE:
-dotcat <file> <dot_separated_key>
-
-EXAMPLE:
-dotcat config.json python.editor.tabSize
-dotcat somefile.toml a.b.c
-""".strip()
+    expected_output = remove_ansi_escape_sequences(HELP.strip())
     actual_output = remove_ansi_escape_sequences(captured_output.getvalue().strip())
     assert actual_output == expected_output
     assert pytest_wrapped_e.type == SystemExit