cheatcheat 0.1.0__py3-none-any.whl

cheatcheat/main.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+import argparse
+import os
+import sys
+import shutil
+import subprocess
+import glob
+import re
+
+try:
+    import yaml
+except ImportError:
+    print("Error: PyYAML is not installed. Please install it using 'pip install PyYAML'.")
+    sys.exit(1)
+
+def load_config(config_path):
+    """Loads configuration from yaml file."""
+    if not os.path.exists(config_path):
+        print(f"Configuration file not found: {config_path}")
+        sys.exit(1)
+    
+    with open(config_path, 'r') as f:
+        try:
+            return yaml.safe_load(f)
+        except yaml.YAMLError as e:
+            print(f"Error parsing config file: {e}")
+            sys.exit(1)
+
+def get_cheatpaths(config):
+    """
+    Returns a list of cheatpaths from config, ensuring local .cheat dirs are included.
+    Returns list of dicts: {'name': str, 'path': str, 'readonly': bool, 'tags': list}
+    """
+    paths = []
+    
+    # 1. Configured paths
+    if 'cheatpaths' in config:
+        for cp in config['cheatpaths']:
+            expanded_path = os.path.expanduser(cp['path'])
+            path_entry = cp.copy()
+            path_entry['path'] = expanded_path
+            paths.append(path_entry)
+            
+    # 2. Local .cheat directory (highest priority, so maybe prepend? README says "append ... to the cheatpath" 
+    # but also "will be treated as the most local ... and will override less local". 
+    # Usually "override" means it is checked *first*.
+    # The README says: "The most global cheatpath is listed first in this file; the most local is listed last."
+    # "For example, if there is a 'tar' cheatsheet on both global and local paths, you'll be presented with the local one by default."
+    # So we should iterate in reverse order to find the "winner", or iterate in priority order (local first) to find the first match.
+    # Let's construct a list where the *last* element has the *highest* priority, matching `conf.yml` structure description.
+    
+    local_cheat = os.path.join(os.getcwd(), '.cheat')
+    if os.path.isdir(local_cheat):
+        paths.append({
+            'name': 'local',
+            'path': local_cheat,
+            'readonly': False,
+            'tags': ['local']
+        })
+        
+    return paths
+
+def find_cheatsheet(cheatname, paths):
+    """
+    Finds a cheatsheet by name. 
+    Searches from most local (last in list) to most global (first in list).
+    Returns (path_entry, full_path) or (None, None).
+    """
+    # Iterate backwards (most local first)
+    for path_entry in reversed(paths):
+        base_dir = path_entry['path']
+        # Check for exact match or match with extension
+        # We need to handle subdirectories too, e.g. cheatname = "foo/bar"
+        
+        # Security check: prevent breakout
+        target_path = os.path.join(base_dir, cheatname)
+        if not os.path.abspath(target_path).startswith(os.path.abspath(base_dir)):
+            continue
+            
+        # Check file exact
+        if os.path.isfile(target_path):
+            return path_entry, target_path
+            
+        # Check file with any extension? README says "file is named 'bar' or 'bar.EXTENSION'"
+        # glob for target_path.*
+        matches = glob.glob(target_path + ".*")
+        if matches:
+            # Pick the first one?
+            return path_entry, matches[0]
+            
+    return None, None
+
+def list_cheatsheets(paths, filter_path_name=None):
+    """Lists all cheatsheets."""
+    sheets = set()
+    
+    # Iterate all paths
+    for entry in paths:
+        if filter_path_name and entry.get('name') != filter_path_name:
+            continue
+            
+        base_dir = entry['path']
+        if not os.path.isdir(base_dir):
+            continue
+            
+        # Walk directory
+        for root, dirs, files in os.walk(base_dir):
+            for file in files:
+                if file.startswith('.'): continue # ignore hidden files
+                
+                # Rel path from base_dir
+                abs_path = os.path.join(root, file)
+                rel_path = os.path.relpath(abs_path, base_dir)
+                
+                # Remove extension for display?
+                # README says: named "tar" or "tar.EXTENSION". 
+                # If we have tar.md, we display tar.
+                base, ext = os.path.splitext(rel_path)
+                # If there are multiple extensions or weird dots, this might be tricky.
+                # But simple logic: if it's a file, it's a cheat.
+                
+                # Check if it matches the pattern
+                sheets.add(base)
+                
+    # Sort and print
+    for sheet in sorted(sheets):
+        print(sheet)
+
+def search_cheatsheets(term, paths):
+    """Searches for term in all cheatsheets."""
+    found = False
+    # Walk all paths
+    for entry in paths:
+        base_dir = entry['path']
+        if not os.path.isdir(base_dir):
+            continue
+            
+        for root, dirs, files in os.walk(base_dir):
+            for file in files:
+                if file.startswith('.'): continue
+                abs_path = os.path.join(root, file)
+                
+                try:
+                    with open(abs_path, 'r', errors='ignore') as f:
+                        lines = f.readlines()
+                        for i, line in enumerate(lines):
+                            if term.lower() in line.lower():
+                                # Calculate sheet name
+                                rel_path = os.path.relpath(abs_path, base_dir)
+                                sheet_name, _ = os.path.splitext(rel_path)
+                                print(f"{sheet_name}:{i+1}: {line.strip()}")
+                                found = True
+                except Exception as e:
+                    # Ignore read errors
+                    pass
+    return found
+
+def edit_cheatsheet(cheatname, paths, config):
+    """Edits a cheatsheet. Handles copy-on-write."""
+    # check if it exists
+    path_entry, full_path = find_cheatsheet(cheatname, paths)
+    
+    editor = config.get('editor', os.environ.get('EDITOR', 'vi'))
+    
+    if path_entry:
+        # Exists
+        if not path_entry.get('readonly', False):
+            # Writable, just open
+            subprocess.call(f"{editor} '{full_path}'", shell=True)
+        else:
+            # Read-only, need to copy to first writable path
+            print(f"Path '{path_entry['name']}' is read-only. Copying to personal path...")
+            
+            # Find last writable path (most local)
+            target_entry = None
+            for entry in reversed(paths): # Iterate in reverse priority order (Local -> Global)
+                if not entry.get('readonly', False):
+                    target_entry = entry
+                    break
+            
+            if not target_entry:
+                print("Error: No writable cheatpath found.")
+                sys.exit(1)
+                
+            # Construct new path
+            # We assume cheatsheet name might have subdirs
+            new_full_path = os.path.join(target_entry['path'], cheatname)
+            
+            # If extension was present in original, try to preserve it?
+            # get extension from full_path
+            _, ext = os.path.splitext(full_path)
+            if ext and not new_full_path.endswith(ext):
+                new_full_path += ext
+                
+            # Ensure dir exists
+            os.makedirs(os.path.dirname(new_full_path), exist_ok=True)
+            
+            # Copy
+            shutil.copy2(full_path, new_full_path)
+            print(f"Copied to {new_full_path}")
+            
+            # Open
+            subprocess.call(f"{editor} '{new_full_path}'", shell=True)
+            
+    else:
+        # Does not exist. Create new.
+        # Find last writable path (most local)
+        target_entry = None
+        for entry in reversed(paths):
+             if not entry.get('readonly', False):
+                target_entry = entry
+                break
+        
+        if not target_entry:
+            print("Error: No writable cheatpath found.")
+            sys.exit(1)
+
+        new_full_path = os.path.join(target_entry['path'], cheatname)
+        # Verify if we should add extension? For now default to no extension or just as is.
+        
+        os.makedirs(os.path.dirname(new_full_path), exist_ok=True)
+        # Open editor (editor will create file usually, or we touch it)
+        # subprocess.call will open it.
+        subprocess.call(f"{editor} '{new_full_path}'", shell=True)
+        
+
+def view_cheatsheet(cheatname, paths, config):
+    """View a cheatsheet."""
+    path_entry, full_path = find_cheatsheet(cheatname, paths)
+    
+    if not path_entry:
+        print(f"No cheatsheet found for '{cheatname}'.")
+        # Optional: Print "Did you mean...?"
+        sys.exit(1)
+        
+    viewer = config.get('viewer', os.environ.get('PAGER', 'less'))
+    
+    # Run viewer
+    try:
+        subprocess.call(f"{viewer} '{full_path}'", shell=True)
+    except Exception as e:
+        print(f"Error opening viewer: {e}")
+        # Fallback to cat
+        with open(full_path, 'r') as f:
+            print(f.read())
+
+def main():
+    parser = argparse.ArgumentParser(description="Create and view interactive cheatsheets.")
+    parser.add_argument("cheatname", nargs="?", help="The name of the cheatsheet to view/edit.")
+    parser.add_argument("-e", "--edit", action="store_true", help="Edit a cheatsheet.")
+    parser.add_argument("-l", "--list", action="store_true", help="List all available cheatsheets.")
+    parser.add_argument("-p", "--path", help="Filter by cheatpath name (used with -l).")
+    parser.add_argument("-s", "--search", help="Search for a term among cheatsheets.")
+    parser.add_argument("-d", "--directories", action="store_true", help="List configured cheatpaths.")
+    parser.add_argument("--conf", default=os.path.expanduser("~/.config/cheat/conf.yml"), help="Path to config file.")
+    
+    # We might need to handle the case where conf.yml is in current dir or specific location?
+    # User env: /Users/cche/git/ch/conf.yml. I will default to look there for this task if not specified? 
+    # Or just rely on the argument. 
+    # For this specific task, the User provided @[conf.yml], so it's likely expected to work with that or default user config.
+    # I'll default to looking in local dir first for dev purposes if not found in standard locations.
+    
+    args = parser.parse_args()
+    
+    # Config resolution
+    config_path = args.conf
+    # Fallback to local 'conf.yml' if default doesn't exist but local does (for dev context)
+    if config_path == os.path.expanduser("~/.config/cheat/conf.yml") and not os.path.exists(config_path):
+        if os.path.exists("conf.yml"):
+            config_path = "conf.yml"
+            
+    config = load_config(config_path)
+    paths = get_cheatpaths(config)
+    
+    if args.directories:
+        for p in paths:
+            print(f"{p['name']}: {p['path']} (readonly: {p.get('readonly', False)})")
+        return
+
+    if args.list:
+        list_cheatsheets(paths, args.path)
+        return
+
+    if args.search:
+        search_cheatsheets(args.search, paths)
+        return
+
+    if args.edit:
+        if not args.cheatname:
+            print("Error: Please specify a cheatsheet to edit.")
+            sys.exit(1)
+        edit_cheatsheet(args.cheatname, paths, config)
+        return
+
+    if args.cheatname:
+        view_cheatsheet(args.cheatname, paths, config)
+        return
+        
+    # If no args, print help
+    parser.print_help()
+
+if __name__ == "__main__":
+    main()

cheatcheat-0.1.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: cheatcheat
+Version: 0.1.0
+Summary: Create and view interactive cheatsheets on the command-line
+Author-email: ChongChong He <chongchonghe@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/chongchonghe/cheatcheat
+Project-URL: Bug Tracker, https://github.com/chongchonghe/cheatcheat/issues
+Keywords: cheat,cheatsheet,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Utilities
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML
+
+
+cheat
+=====
+
+`cheat` allows you to create and view interactive cheatsheets on the
+command-line. It was designed to help remind \*nix system administrators of
+options for commands that they use frequently, but not frequently enough to
+remember.
+
+Example
+-------
+The next time you're forced to disarm a nuclear weapon without consulting
+Google, you may run:
+
+```sh
+cheat tar
+```
+
+You will be presented with a cheatsheet resembling the following:
+
+```sh
+# To extract an uncompressed archive:
+tar -xvf '/path/to/foo.tar'
+
+# To extract a .gz archive:
+tar -xzvf '/path/to/foo.tgz'
+
+# To create a .gz archive:
+tar -czvf '/path/to/foo.tgz' '/path/to/foo/'
+
+# To extract a .bz2 archive:
+tar -xjvf '/path/to/foo.tgz'
+
+# To create a .bz2 archive:
+tar -cjvf '/path/to/foo.tgz' '/path/to/foo/'
+```
+
+Usage
+-----
+To view a cheatsheet:
+
+```sh
+cheat tar      # a "top-level" cheatsheet
+cheat foo/bar  # a "nested" cheatsheet
+```
+
+To edit a cheatsheet:
+
+```sh
+cheat -e tar     # opens the "tar" cheatsheet for editing, or creates it if it does not exist
+cheat -e foo/bar # nested cheatsheets are accessed like this
+```
+
+To view the configured cheatpaths:
+
+```sh
+cheat -d
+```
+
+To list all available cheatsheets:
+
+```sh
+cheat -l
+```
+
+To list all cheatsheets on the "personal" path:
+
+```sh
+cheat -l -p personal
+```
+
+To search for the phrase "ssh" among cheatsheets:
+
+```sh
+cheat -s ssh
+```
+
+Cheatsheets
+-----------
+Cheatsheets are plain-text files with optional file extensions. When the extension is excluded, they are named
+according to the command used to view them:
+
+```sh
+cheat tar     # file is named "tar" or "tar.EXTENSION"
+cheat foo/bar # file is named "bar" or "bar.EXTENSION", in a "foo" subdirectory
+```
+
+Cheatpaths
+----------
+Cheatsheets are stored on "cheatpaths", which are directories that contain
+cheatsheets. Cheatpaths are specified in the `conf.yml` file.
+
+It can be useful to configure `cheat` against multiple cheatpaths. A common
+pattern is to store cheatsheets from multiple repositories on individual
+cheatpaths:
+
+```yaml
+# conf.yml:
+# ...
+cheatpaths:
+  - name: community                   # a name for the cheatpath
+    path: ~/documents/cheat/community # the path's location on the filesystem
+    tags: [ community ]               # these tags will be applied to all sheets on the path
+    readonly: true                    # if true, `cheat` will not create new cheatsheets here
+
+  - name: personal
+    path: ~/documents/cheat/personal  # this is a separate directory and repository than above
+    tags: [ personal ]
+    readonly: false                   # new sheets may be written here
+# ...
+```
+
+The `readonly` option instructs `cheat` not to edit (or create) any cheatsheets
+on the path. This is useful to prevent merge-conflicts from arising on upstream
+cheatsheet repositories.
+
+If a user attempts to edit a cheatsheet on a read-only cheatpath, `cheat` will
+transparently copy that sheet to the first writeable directory in 'cheatpaths' before opening it for
+editing.
+

cheatcheat-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+cheatcheat/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cheatcheat/main.py,sha256=MslE6blgxVnxjGzZ3mHjpeMAoz71tGK270D_xxFHOAM,11583
+cheatcheat-0.1.0.dist-info/METADATA,sha256=g6KNvbz6bggK9jv71hqSHdnVQkDDCyBSNLQL0aGL0_4,3648
+cheatcheat-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cheatcheat-0.1.0.dist-info/entry_points.txt,sha256=4LuOywarRBwVxCbpkLTLzkZEb-8fBIvMSlNTsLXbuIc,47
+cheatcheat-0.1.0.dist-info/top_level.txt,sha256=i6HZwer-VZ2knnrjEZFukKETIudfxQtk8dK1i4_rhw4,11
+cheatcheat-0.1.0.dist-info/RECORD,,

cheatcheat-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cheatcheat-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cheat = cheatcheat.main:main

cheatcheat-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cheatcheat