codefetch-cli 1.2.2__py3-none-any.whl → 1.2.4__py3-none-any.whl

codefetch/__init__.py

@@ -1,5 +1,160 @@
 """
-CodeFetch - CLI tool to fetch code files from GitHub repositories.
+CodeFetch - Easily preview and download code files from GitHub repositories.
+
+Usage in Python:
+    import codefetch as cf
+
+    # 1. Fetch file content as string:
+    content = cf.get("torvalds/linux", "Makefile")
+    # or shorthand target string:
+    content = cf.get("torvalds/linux/Makefile")
+
+    # 2. Download file to local disk:
+    cf.download("torvalds/linux", "Makefile", output="linux_makefile.txt")
+
+    # 3. List available code files:
+    files = cf.list("torvalds/linux")
 """
 
-__version__ = "1.2.2"
+__version__ = "1.2.4"
+
+
+def get(target, filename=None, branch=None):
+    """
+    Fetch and return the text content of a file from GitHub.
+
+    Args:
+        target: 'owner/repo' or full path 'owner/repo/path/to/file' or full GitHub URL.
+        filename: Optional path to file in repo if target is 'owner/repo'.
+        branch: Branch name (default: None, automatically detects repo default branch).
+
+    Returns:
+        str: File content.
+
+    Raises:
+        FileNotFoundError: If the file does not exist in the repository.
+        ValueError: If arguments cannot be resolved into a repository and filename.
+    """
+    import urllib.request
+    from .cli import (
+        get_default_branch,
+        check_branch_exists,
+        fetch_raw_single,
+        get_repo_tree,
+        resolve_file_in_tree,
+        parse_repo_identifier,
+        resolve_invocation,
+    )
+
+    if filename:
+        owner, repo = parse_repo_identifier(target)
+        file_path = filename.strip("/\\")
+    else:
+        owner, repo, resolved_branch, file_path = resolve_invocation(
+            [target], None, None, branch, None, None
+        )
+        if resolved_branch:
+            branch = resolved_branch
+
+    if not owner or not repo or not file_path:
+        raise ValueError(f"Could not resolve owner, repo, and filename from target='{target}', filename='{filename}'")
+
+    target_branch = branch
+    if not target_branch:
+        target_branch = get_default_branch(owner, repo)
+    elif not check_branch_exists(owner, repo, target_branch):
+        target_branch = get_default_branch(owner, repo)
+
+    # 1. Try fast direct raw fetch
+    content = fetch_raw_single(owner, repo, target_branch, file_path)
+    if content is not None:
+        return content
+
+    # 2. Try repository tree search
+    tree_data = get_repo_tree(owner, repo, target_branch)
+    matched = resolve_file_in_tree(tree_data, file_path)
+    if matched:
+        url = f"https://raw.githubusercontent.com/{owner}/{repo}/{target_branch}/{matched}"
+        req = urllib.request.Request(url, headers={"User-Agent": "codefetch"})
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            return resp.read().decode("utf-8")
+
+    raise FileNotFoundError(f"File '{file_path}' not found in {owner}/{repo} ({target_branch})")
+
+
+def download(target, filename=None, output=None, branch=None):
+    """
+    Download a file from GitHub and save it locally.
+
+    Args:
+        target: 'owner/repo' or full path 'owner/repo/path/to/file'.
+        filename: Optional path to file in repo if target is 'owner/repo'.
+        output: Destination filename/path on local disk (default: original filename).
+        branch: Branch name (default: None, automatically detects repo default branch).
+
+    Returns:
+        str: Path to the downloaded file.
+    """
+    content = get(target, filename=filename, branch=branch)
+    dest_name = output
+    if not dest_name:
+        resolved_file = filename if filename else target.rsplit("/", 1)[-1]
+        dest_name = resolved_file.rsplit("/", 1)[-1]
+
+    with open(dest_name, "w", encoding="utf-8") as f:
+        f.write(content)
+
+    return dest_name
+
+
+def list(target, branch=None):
+    """
+    List supported code files in a repository.
+
+    Args:
+        target: 'owner/repo' or repository URL.
+        branch: Branch name (default: None, automatically detects repo default branch).
+
+    Returns:
+        list[str]: Relative paths of code files in the repository.
+    """
+    from .cli import (
+        parse_repo_identifier,
+        get_default_branch,
+        check_branch_exists,
+        get_repo_tree,
+        CODE_EXTENSIONS,
+        NAMED_FILES,
+    )
+
+    owner, repo = parse_repo_identifier(target)
+    if not owner or not repo:
+        raise ValueError(f"Invalid repository identifier: '{target}'")
+
+    target_branch = branch
+    if not target_branch or not check_branch_exists(owner, repo, target_branch):
+        target_branch = get_default_branch(owner, repo)
+
+    tree_data = get_repo_tree(owner, repo, target_branch)
+    files = []
+    for item in tree_data.get("tree", []):
+        if item.get("type") != "blob":
+            continue
+        path = item.get("path", "")
+        base_name = path.rsplit("/", 1)[-1].lower()
+        suffix = ""
+        if "." in base_name:
+            suffix = "." + base_name.rsplit(".", 1)[-1]
+        if suffix in CODE_EXTENSIONS or base_name in NAMED_FILES:
+            files.append(path)
+
+    files.sort(key=str.lower)
+    return files
+
+
+__all__ = [
+    "__version__",
+    "get",
+    "download",
+    "list",
+]

codefetch/cli.py

@@ -14,10 +14,12 @@ from pathlib import Path
 
 DEFAULT_OWNER = None
 DEFAULT_REPO = None
-DEFAULT_BRANCH = "main"
+DEFAULT_BRANCH = None
 
 CONFIG_FILE = Path.home() / ".codefetch.json"
 
+__version__ = "1.2.4"
+
 # Supported code, data, and config extensions
 CODE_EXTENSIONS = {
     # Data & Tables
@@ -56,85 +58,86 @@ CodeFetch - Download single code files from GitHub without cloning entire repos.
 
 USAGE:
   codefetch <owner>/<repo> <filename>      Download a file from any GitHub repository
-  codefetch <filename>                     Download a file (requires default repository)
-
-QUICK EXAMPLES:
-  Download a file:
-    codefetch torvalds/linux Makefile        Save Makefile to current directory
-    codefetch owner/repo main.py             Save main.py from a repository
-    codefetch owner/repo data.csv -o out.csv Save with a custom output filename
-
-  View code in terminal (without downloading):
-    codefetch -s owner/repo main.py          Display main.py in terminal
-    codefetch -s torvalds/linux Makefile     Display Makefile in terminal
-
-  Browse files and repositories:
-    codefetch -l owner/repo                  List all code files in a repository
-    codefetch -R -u <username>               List all public repositories of a user
-    codefetch -R <username>                  List all public repositories of a user
-
-SETTINGS & DEFAULTS (Optional):
-  codefetch --set-default <owner/repo>     Set a permanent default repository
-  codefetch --set-default-user <username>  Set a permanent default GitHub user
-  codefetch --config                       View current saved settings
-  codefetch --reset-config                 Clear saved settings
-
-OPTIONS:
-  -s, --show             View file contents in terminal instead of saving
-  -o, --output <file>    Custom filename or path to save the downloaded file
-  -l, --list [repo]      List available code files in a repository
-  -R, --repos [user]     List all public repositories for a user
-  -r, --repo <name>      Specify repository name or URL
-  -u, --user <name>      Specify GitHub username
-  -b, --branch <name>    Specify branch name (default: main)
-  -v, --version          Show version number
-  -h, --help             Show this help guide
+  codefetch <filename>                     Download a file (uses saved default repo)
+  codefetch -s <owner>/<repo> <filename>   Preview file in terminal without saving
+  codefetch -l <owner>/<repo>              List all code files in a repository
+  codefetch -R <username>                  List public repositories for a user
+
+POPULAR EXAMPLES:
+  # Download from any repository:
+  codefetch owner/repo main.py
+  codefetch torvalds/linux Makefile
+
+  # Preview code directly in terminal:
+  codefetch -s owner/repo app.js
+  codefetch -s torvalds/linux Makefile
+
+  # Save with a custom name or path:
+  codefetch owner/repo data.csv -o my_data.csv
+
+  # Explore repositories and files:
+  codefetch -l torvalds/linux              # list files in a repo
+  codefetch -R torvalds                    # list repos belonging to user
+
+SETTING A DEFAULT REPOSITORY (OPTIONAL):
+  If you frequently work with the same repo, you can set it as default:
+  codefetch --set-default owner/repo       # sets default repo
+  codefetch script.py                      # now you don't need to type owner/repo!
+  codefetch --config                       # view active configuration
+  codefetch --reset-config                 # reset all defaults
+
+FLAGS & OPTIONS:
+  -s, --show                Print file content to terminal instead of downloading
+  -o, --output <file>       Specify output filename or path
+  -l, --list                List available code files in the repository
+  -R, --repos               List public repositories for a GitHub user
+  -r, --repo <repo>         Specify repository name or URL
+  -u, --user <user>         Specify GitHub username / organization
+  -b, --branch <branch>     Specify branch name (default: repository default branch)
+  --set-default <repo>      Save default repository (e.g. owner/repo)
+  --set-default-user <user> Save default user/organization
+  --config                  Show current saved configuration
+  --reset-config            Reset configuration back to defaults
+  -v, --version             Show version number
+  -h, --help                Show this help message
 """
 
+_REPO_DEFAULT_BRANCH_CACHE = {}
+_REPO_BRANCHES_CACHE = {}
+
 
 def load_config():
-    """Load configuration from environment variables and local config file."""
-    config = {
-        "owner": os.environ.get("CODEFETCH_USER", DEFAULT_OWNER),
-        "repo": os.environ.get("CODEFETCH_REPO", DEFAULT_REPO),
-        "branch": os.environ.get("CODEFETCH_BRANCH", DEFAULT_BRANCH),
-    }
+    """Load user configuration from ~/.codefetch.json."""
     if CONFIG_FILE.exists():
         try:
             with open(CONFIG_FILE, "r", encoding="utf-8") as f:
-                saved = json.load(f)
-                if isinstance(saved, dict):
-                    if saved.get("owner"):
-                        config["owner"] = saved["owner"]
-                    if saved.get("repo"):
-                        config["repo"] = saved["repo"]
-                    if saved.get("branch"):
-                        config["branch"] = saved["branch"]
+                data = json.load(f)
+                return {
+                    "owner": data.get("owner"),
+                    "repo": data.get("repo"),
+                }
         except Exception:
-            pass
-    return config
+            return {}
+    return {}
 
 
-def save_config(owner=None, repo=None, branch=None):
-    """Save configuration to ~/.codefetch.json."""
-    config = load_config()
-    if owner:
-        config["owner"] = owner
-    if repo:
-        config["repo"] = repo
-    if branch:
-        config["branch"] = branch
+def save_config(owner=None, repo=None):
+    """Save user configuration to ~/.codefetch.json (no branch saved in config)."""
+    cfg = load_config()
+    if owner is not None:
+        cfg["owner"] = owner
+    if repo is not None:
+        cfg["repo"] = repo
+
     try:
         with open(CONFIG_FILE, "w", encoding="utf-8") as f:
-            json.dump(config, f, indent=2)
-        return True
+            json.dump(cfg, f, indent=2)
     except Exception as e:
-        print(f"Error saving configuration: {e}")
-        return False
+        print(f"Warning: Could not save configuration: {e}")
 
 
 def get_headers():
-    """Get HTTP headers for GitHub requests."""
+    """Build request headers, attaching GITHUB_TOKEN if present in environment."""
     headers = {
         "User-Agent": "codefetch",
         "Accept": "application/vnd.github+json",
@@ -146,10 +149,10 @@ def get_headers():
 
 
 def get_json(url):
-    """Fetch and decode JSON from a URL."""
-    request = urllib.request.Request(url, headers=get_headers())
-    with urllib.request.urlopen(request, timeout=15) as response:
-        return json.loads(response.read().decode("utf-8"))
+    """Fetch JSON from GitHub API with rate limit handling."""
+    req = urllib.request.Request(url, headers=get_headers())
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        return json.loads(resp.read().decode("utf-8"))
 
 
 def parse_repo_identifier(repo_str, default_owner=None):
@@ -170,37 +173,112 @@ def parse_repo_identifier(repo_str, default_owner=None):
     return default_owner, repo_str.removesuffix(".git")
 
 
-def get_repo_tree(owner, repo, branch="main"):
-    """Fetch the Git tree for a repository, with fallback to master if main is absent."""
-    url = f"https://api.github.com/repos/{owner}/{repo}/git/trees/{branch}?recursive=1"
+def get_default_branch(owner, repo):
+    """
+    Get the default branch of a repository (e.g. 'main', 'master', 'unstable').
+    Queries GitHub API and caches the result. Falls back to probing if rate limited.
+    """
+    key = f"{owner.lower()}/{repo.lower()}"
+    if key in _REPO_DEFAULT_BRANCH_CACHE:
+        return _REPO_DEFAULT_BRANCH_CACHE[key]
+
+    try:
+        url = f"https://api.github.com/repos/{owner}/{repo}"
+        data = get_json(url)
+        def_b = data.get("default_branch")
+        if def_b:
+            _REPO_DEFAULT_BRANCH_CACHE[key] = def_b
+            return def_b
+    except Exception:
+        pass
+
+    # Fast fallback probe via CDN if API is unavailable or rate-limited
+    for b in ("main", "master"):
+        try:
+            req = urllib.request.Request(
+                f"https://raw.githubusercontent.com/{owner}/{repo}/{b}/README.md",
+                headers=get_headers(),
+            )
+            with urllib.request.urlopen(req, timeout=5):
+                _REPO_DEFAULT_BRANCH_CACHE[key] = b
+                return b
+        except Exception:
+            continue
+
+    return "main"
+
+
+def get_repo_branches(owner, repo):
+    """Fetch the list of all branch names in a repository."""
+    key = f"{owner.lower()}/{repo.lower()}"
+    if key in _REPO_BRANCHES_CACHE:
+        return _REPO_BRANCHES_CACHE[key]
+
+    try:
+        url = f"https://api.github.com/repos/{owner}/{repo}/branches?per_page=100"
+        data = get_json(url)
+        branches = [b["name"] for b in data if isinstance(b, dict) and b.get("name")]
+        if branches:
+            _REPO_BRANCHES_CACHE[key] = branches
+            return branches
+    except Exception:
+        pass
+    return []
+
+
+def check_branch_exists(owner, repo, branch):
+    """Check if a specific branch exists in a repository."""
+    if not branch:
+        return False
+    branches = get_repo_branches(owner, repo)
+    if branches:
+        return branch in branches
     try:
-        return get_json(url)
+        get_json(f"https://api.github.com/repos/{owner}/{repo}/branches/{branch}")
+        return True
     except urllib.error.HTTPError as e:
-        if e.code == 404 and branch == "main":
-            url_master = f"https://api.github.com/repos/{owner}/{repo}/git/trees/master?recursive=1"
-            try:
-                return get_json(url_master)
-            except Exception:
-                pass
+        if e.code == 404:
+            return False
+        return True
+    except Exception:
+        return True
+
+
+def fetch_raw_single(owner, repo, branch, clean_filename):
+    """
+    Direct raw fetch from raw.githubusercontent.com for a specific branch.
+    Returns content string or None if 404.
+    """
+    url = f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{clean_filename}"
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "codefetch"})
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            return resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            return None
+        raise
+    except UnicodeDecodeError:
         raise
 
 
+def get_repo_tree(owner, repo, branch):
+    """Fetch the Git tree for a repository on a given branch."""
+    url = f"https://api.github.com/repos/{owner}/{repo}/git/trees/{branch}?recursive=1"
+    return get_json(url)
+
+
 def get_user_repos(owner):
-    """Fetch public repositories for a given GitHub owner."""
+    """Fetch public repositories list for a user."""
     url = f"https://api.github.com/users/{owner}/repos?per_page=100&sort=updated"
-    try:
-        return get_json(url)
-    except Exception:
-        return []
+    return get_json(url)
 
 
 def list_repos(owner=None, default_repo=None):
-    """List all public repositories for the owner."""
+    """List all public repositories for a GitHub user with clean spacing."""
     if not owner:
-        print("Error: No GitHub user specified.\n")
-        print("Usage:")
-        print("  codefetch -R <username>")
-        print("  codefetch -R -u <username>")
+        print("Error: No GitHub username specified.")
+        print("Usage: codefetch --repos <username>")
         return
 
     try:
@@ -209,19 +287,21 @@ def list_repos(owner=None, default_repo=None):
             print(f"No public repositories found for user '{owner}'.")
             return
 
-        print(f"Repositories for '{owner}':\n")
-        for r in repos:
+        print(f"Public repositories for '{owner}' ({len(repos)} total):\n")
+        for i, r in enumerate(repos, 1):
             name = r.get("name", "")
-            desc = r.get("description") or ""
+            desc = (r.get("description") or "").strip()
             is_def = " (default)" if default_repo and name.lower() == default_repo.lower() else ""
-            marker = "*" if is_def else "-"
-            desc_text = f" - {desc}" if desc else ""
-            print(f"  {marker} {name}{is_def}{desc_text}")
+            print(f"  {i:>2}. {name}{is_def}")
+            if desc:
+                print(f"      {desc}")
+            print()
 
-        print("\nCommands:")
-        print(f"  codefetch -l {owner}/<repo>                  List files in a repository")
-        print(f"  codefetch {owner}/<repo> <filename>          Download a file from a repository")
-        print(f"  codefetch --set-default {owner}/<repo>       Set default repository")
+        print("Commands:")
+        print(f"  codefetch {owner}/<repo> <filename>          Download a file")
+        print(f"  codefetch -s {owner}/<repo> <filename>       Preview file in terminal")
+        print(f"  codefetch -l {owner}/<repo>                  List files in repository")
+        print(f"  codefetch --set-default {owner}/<repo>       Set as default repository")
 
     except urllib.error.HTTPError as e:
         print(f"Could not list repositories: HTTP {e.code}")
@@ -231,8 +311,8 @@ def list_repos(owner=None, default_repo=None):
         print(f"Could not list repositories: {e}")
 
 
-def list_files(owner, repo, branch="main"):
-    """List code files in a repository."""
+def list_files(owner, repo, branch=None):
+    """List code files in a repository, with automatic branch detection and fallback."""
     if not owner or not repo:
         print("Error: No repository specified to list.\n")
         print("Usage:")
@@ -240,8 +320,25 @@ def list_files(owner, repo, branch="main"):
         print("  codefetch -u <owner> -r <repo> -l")
         return
 
+    target_branch = branch
+    default_branch = get_default_branch(owner, repo)
+
+    # If branch was specified by user, verify it first
+    if target_branch:
+        if not check_branch_exists(owner, repo, target_branch):
+            print(f"Notice: Branch '{target_branch}' was not found in {owner}/{repo}.")
+            available_branches = get_repo_branches(owner, repo)
+            if available_branches:
+                shown = available_branches[:15]
+                extra = f" (+{len(available_branches) - 15} more)" if len(available_branches) > 15 else ""
+                print(f"Available branches in {owner}/{repo}: {', '.join(shown)}{extra}")
+            print(f"Listing files from default branch '{default_branch}' instead:\n")
+            target_branch = default_branch
+    else:
+        target_branch = default_branch
+
     try:
-        data = get_repo_tree(owner, repo, branch)
+        data = get_repo_tree(owner, repo, target_branch)
         if data.get("truncated"):
             print("Warning: GitHub returned a truncated file list.")
 
@@ -262,10 +359,10 @@ def list_files(owner, repo, branch="main"):
         files.sort(key=str.lower)
 
         if not files:
-            print(f"No supported code files found in {owner}/{repo}.")
+            print(f"No supported code files found in {owner}/{repo} ({target_branch}).")
             return
 
-        print(f"Available files in {owner}/{repo} ({branch}):\n")
+        print(f"Available files in {owner}/{repo} ({target_branch}):\n")
         for i, path in enumerate(files, 1):
             print(f"{i:>3}. {path}")
 
@@ -335,9 +432,9 @@ def find_file_in_other_repos(owner, current_repo, target_filename):
             r_name = r.get("name")
             if not r_name or (current_repo and r_name.lower() == current_repo.lower()):
                 continue
-            default_branch = r.get("default_branch", "main")
+            default_b = r.get("default_branch") or "main"
             try:
-                tree_data = get_repo_tree(owner, r_name, default_branch)
+                tree_data = get_repo_tree(owner, r_name, default_b)
                 match = resolve_file_in_tree(tree_data, target_filename)
                 if match:
                     return r_name, match
@@ -348,9 +445,14 @@ def find_file_in_other_repos(owner, current_repo, target_filename):
     return None, None
 
 
-def fetch_file(filename, owner=None, repo=None, branch=DEFAULT_BRANCH,
+def fetch_file(filename, owner=None, repo=None, branch=None,
                show=False, output=None):
-    """Fetch or download a file from GitHub."""
+    """
+    Fetch or download a file from GitHub.
+    - If branch is None: fetches the default branch of the repository.
+    - If branch is specified: tries that branch first; if not found, shows message,
+      displays all available branches, and falls back to default branch.
+    """
     if not owner or not repo:
         print("Error: No GitHub repository specified.\n")
         print("Usage:")
@@ -368,50 +470,159 @@ def fetch_file(filename, owner=None, repo=None, branch=DEFAULT_BRANCH,
         with urllib.request.urlopen(req, timeout=15) as resp:
             return resp.read().decode("utf-8")
 
-    # 1. Direct raw fetch first (fastest, preserves GitHub API rate limit)
-    raw_base = f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}"
-    url = f"{raw_base}/{clean_filename}"
-
     content = None
     resolved_path = clean_filename
+    actual_branch = None
 
-    try:
-        content = download_url(url)
-    except urllib.error.HTTPError as e:
-        if e.code == 404:
-            # 2. Direct fetch 404ed. Try smart resolution with repo tree
+    default_branch = get_default_branch(owner, repo)
+
+    # Case A: Branch parameter was explicitly entered by the user
+    if branch:
+        # First, check if the specified branch exists
+        branch_exists = check_branch_exists(owner, repo, branch)
+
+        if not branch_exists:
+            print(f"Notice: Branch '{branch}' was not found in {owner}/{repo}.")
+            available_branches = get_repo_branches(owner, repo)
+            if available_branches:
+                shown = available_branches[:15]
+                extra = f" (+{len(available_branches) - 15} more)" if len(available_branches) > 15 else ""
+                print(f"Available branches in {owner}/{repo}: {', '.join(shown)}{extra}")
+            print(f"Trying default branch '{default_branch}'...")
+
+            # Fall back to default branch
+            actual_branch = default_branch
+            try:
+                content = fetch_raw_single(owner, repo, default_branch, clean_filename)
+            except UnicodeDecodeError:
+                print("The file is not UTF-8 text, so it cannot be displayed or saved as text.")
+                return
+            except Exception:
+                pass
+
+            if content is None:
+                # Try tree on default branch
+                try:
+                    tree_data = get_repo_tree(owner, repo, default_branch)
+                    matched = resolve_file_in_tree(tree_data, clean_filename)
+                    if matched:
+                        resolved_path = matched
+                        content = download_url(f"https://raw.githubusercontent.com/{owner}/{repo}/{default_branch}/{resolved_path}")
+                        if resolved_path != clean_filename:
+                            print(f"(Resolved '{clean_filename}' -> '{resolved_path}')")
+                except Exception:
+                    pass
+
+            if content is None:
+                print(f"File not found: '{clean_filename}' in {owner}/{repo} (checked '{branch}' and default '{default_branch}').")
+                print(f"To fetch from a specific branch: codefetch -b <branch> {owner}/{repo} {clean_filename}")
+                return
+
+        else:
+            # The specified branch exists! First try direct fetch from it
+            actual_branch = branch
+            try:
+                content = fetch_raw_single(owner, repo, branch, clean_filename)
+            except UnicodeDecodeError:
+                print("The file is not UTF-8 text, so it cannot be displayed or saved as text.")
+                return
+            except Exception:
+                pass
+
+            if content is None:
+                # Direct raw 404ed, search tree of the specified branch
+                try:
+                    tree_data = get_repo_tree(owner, repo, branch)
+                    matched = resolve_file_in_tree(tree_data, clean_filename)
+                    if matched:
+                        resolved_path = matched
+                        content = download_url(f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{resolved_path}")
+                        if resolved_path != clean_filename:
+                            print(f"(Resolved '{clean_filename}' -> '{resolved_path}')")
+                except Exception:
+                    pass
+
+            # If file not in specified branch, check default branch as well
+            if content is None and branch.lower() != default_branch.lower():
+                print(f"Notice: File '{clean_filename}' not found on branch '{branch}'.")
+                available_branches = get_repo_branches(owner, repo)
+                if available_branches:
+                    shown = available_branches[:15]
+                    extra = f" (+{len(available_branches) - 15} more)" if len(available_branches) > 15 else ""
+                    print(f"Available branches in {owner}/{repo}: {', '.join(shown)}{extra}")
+                print(f"Trying default branch '{default_branch}'...")
+
+                try:
+                    content = fetch_raw_single(owner, repo, default_branch, clean_filename)
+                    if content is not None:
+                        actual_branch = default_branch
+                except Exception:
+                    pass
+
+                if content is None:
+                    try:
+                        tree_data = get_repo_tree(owner, repo, default_branch)
+                        matched = resolve_file_in_tree(tree_data, clean_filename)
+                        if matched:
+                            resolved_path = matched
+                            actual_branch = default_branch
+                            content = download_url(f"https://raw.githubusercontent.com/{owner}/{repo}/{default_branch}/{resolved_path}")
+                            if resolved_path != clean_filename:
+                                print(f"(Resolved '{clean_filename}' -> '{resolved_path}')")
+                    except Exception:
+                        pass
+
+            if content is None:
+                print(f"File not found: '{clean_filename}' in {owner}/{repo} ({branch}).")
+                return
+
+    # Case B: No branch was specified (branch is None) -> fetch repo default branch
+    else:
+        actual_branch = default_branch
+        try:
+            content = fetch_raw_single(owner, repo, default_branch, clean_filename)
+        except UnicodeDecodeError:
+            print("The file is not UTF-8 text, so it cannot be displayed or saved as text.")
+            return
+        except urllib.error.HTTPError as e:
+            if e.code != 404:
+                print(f"Download failed: HTTP {e.code}")
+                return
+        except urllib.error.URLError:
+            print("Could not connect to GitHub.")
+            return
+
+        if content is None:
+            # Tree search on default branch
             try:
-                tree_data = get_repo_tree(owner, repo, branch)
+                tree_data = get_repo_tree(owner, repo, default_branch)
                 matched = resolve_file_in_tree(tree_data, clean_filename)
                 if matched:
                     resolved_path = matched
-                    content = download_url(f"{raw_base}/{resolved_path}")
+                    content = download_url(f"https://raw.githubusercontent.com/{owner}/{repo}/{default_branch}/{resolved_path}")
                     if resolved_path != clean_filename:
                         print(f"(Resolved '{clean_filename}' -> '{resolved_path}')")
                 else:
                     # Check other public repositories for the same user
                     other_repo, other_match = find_file_in_other_repos(owner, repo, clean_filename)
                     if other_repo:
-                        print(f"File not found: '{clean_filename}' in {owner}/{repo}.")
+                        print(f"File not found: '{clean_filename}' in {owner}/{repo} ({default_branch}).")
                         print(f"\n[Tip] Found '{other_match}' in repository '{other_repo}'!")
                         print(f"To fetch it, run:\n  codefetch {owner}/{other_repo} {other_match}")
                         return
                     else:
-                        print(f"File not found: '{clean_filename}' in {owner}/{repo}.")
+                        print(f"File not found: '{clean_filename}' in {owner}/{repo} ({default_branch}).")
                         print(f"Run 'codefetch -l {owner}/{repo}' to see available files.")
                         return
+            except urllib.error.HTTPError as e:
+                print(f"Could not search repository: HTTP {e.code}")
+                return
+            except urllib.error.URLError:
+                print("Could not connect to GitHub.")
+                return
             except Exception:
-                print(f"File not found: '{clean_filename}' in {owner}/{repo}.")
+                print(f"File not found: '{clean_filename}' in {owner}/{repo} ({default_branch}).")
                 return
-        else:
-            print(f"Download failed: HTTP {e.code}")
-            return
-    except urllib.error.URLError:
-        print("Could not connect to GitHub.")
-        return
-    except UnicodeDecodeError:
-        print("The file is not UTF-8 text, so it cannot be displayed or saved as text.")
-        return
 
     if content is None:
         return
@@ -423,7 +634,7 @@ def fetch_file(filename, owner=None, repo=None, branch=DEFAULT_BRANCH,
         try:
             with open(out_name, "w", encoding="utf-8") as f:
                 f.write(content)
-            print(f"Downloaded: {out_name} (from {owner}/{repo})")
+            print(f"Downloaded: {out_name} (from {owner}/{repo}@{actual_branch})")
         except Exception as e:
             print(f"Error saving file '{out_name}': {e}")
 
@@ -440,87 +651,38 @@ class CodefetchParser(argparse.ArgumentParser):
 
 
 def build_parser():
-    """Build argument parser with full CLI options."""
     parser = CodefetchParser(
         prog="codefetch",
-        add_help=True,
-    )
-    parser.add_argument(
-        "args",
-        nargs="*",
-        help="Target specification: <owner>/<repo> <filename> or <filename>",
-    )
-    parser.add_argument(
-        "-r", "--repo",
-        default=None,
-        help="Repository name or URL (e.g. repo or owner/repo)",
-    )
-    parser.add_argument(
-        "-u", "--user",
-        default=None,
-        help="GitHub user/org name",
-    )
-    parser.add_argument(
-        "-b", "--branch",
-        default=None,
-        help=f"Branch name (default: {DEFAULT_BRANCH})",
-    )
-    parser.add_argument(
-        "-l", "--list",
-        action="store_true",
-        help="List available code files in the repository",
-    )
-    parser.add_argument(
-        "-R", "--repos",
-        action="store_true",
-        help="List all public repositories for a user",
-    )
-    parser.add_argument(
-        "-s", "--show",
-        action="store_true",
-        help="Display file content in terminal without saving to disk",
-    )
-    parser.add_argument(
-        "-o", "--output",
-        default=None,
-        help="Custom destination filename or output path",
-    )
-    parser.add_argument(
-        "--set-default",
-        metavar="REPO",
-        help="Set persistent default repository in local config",
-    )
-    parser.add_argument(
-        "--set-default-user",
-        metavar="USER",
-        help="Set persistent default GitHub user in local config",
-    )
-    parser.add_argument(
-        "--config",
-        action="store_true",
-        help="Display current CodeFetch configuration",
-    )
-    parser.add_argument(
-        "--reset-config",
-        action="store_true",
-        help="Reset configuration back to defaults",
-    )
-    parser.add_argument(
-        "-v", "--version",
-        action="version",
-        version="codefetch 1.2.2",
+        description="Fetch code files from GitHub repositories.",
+        add_help=False,
     )
+
+    parser.add_argument("args", nargs="*", help="Repository and filename targets")
+    parser.add_argument("-s", "--show", action="store_true", help="Print file content to terminal")
+    parser.add_argument("-l", "--list", action="store_true", help="List code files in repository")
+    parser.add_argument("-R", "--repos", action="store_true", help="List public repositories for a user")
+    parser.add_argument("-r", "--repo", type=str, help="Repository name or URL")
+    parser.add_argument("-u", "--user", type=str, help="GitHub username")
+    parser.add_argument("-b", "--branch", type=str, default=None, help="Branch name (default: repository default branch)")
+    parser.add_argument("-o", "--output", type=str, help="Custom output filename or path")
+    parser.add_argument("--set-default", type=str, help="Save default repository (e.g. owner/repo)")
+    parser.add_argument("--set-default-user", type=str, help="Save default GitHub user")
+    parser.add_argument("--config", action="store_true", help="Display active configuration")
+    parser.add_argument("--reset-config", action="store_true", help="Reset configuration back to defaults")
+    parser.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("-h", "--help", action="help", help="Show help message")
+
     return parser
 
 
 def resolve_invocation(positional_args, repo_flag, user_flag, branch_flag,
-                       default_owner, default_repo, default_branch):
+                       default_owner, default_repo):
     """
     Resolve arguments into (owner, repo, branch, filename).
     """
     owner = user_flag or default_owner
     repo = default_repo
-    branch = branch_flag or default_branch
+    branch = branch_flag  # None if not provided
     filename = None
 
     if repo_flag:
@@ -579,7 +741,6 @@ def main():
     config = load_config()
     default_owner = config.get("owner", DEFAULT_OWNER)
     default_repo = config.get("repo", DEFAULT_REPO)
-    default_branch = config.get("branch", DEFAULT_BRANCH)
 
     # Handle --reset-config
     if args.reset_config:
@@ -615,12 +776,12 @@ def main():
         print("CodeFetch Configuration:")
         print(f"  Default User:        {default_owner or 'None (not set)'}")
         print(f"  Default Repository:  {default_repo or 'None (not set)'}")
-        print(f"  Default Branch:      {default_branch}")
+        print("  Default Branch:      None (auto-detect repository default)")
         print(f"  Config File:         {CONFIG_FILE}")
         return
 
     owner = args.user or default_owner
-    branch = args.branch or default_branch
+    branch = args.branch  # None if not provided
 
     # Handle --repos (list repositories)
     if args.repos:
@@ -665,7 +826,6 @@ def main():
         args.branch,
         default_owner,
         default_repo,
-        default_branch,
     )
 
     if not resolved_filename:

{codefetch_cli-1.2.2.dist-info → codefetch_cli-1.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codefetch-cli
-Version: 1.2.2
+Version: 1.2.4
 Summary: Quickly fetch code files from GitHub repositories with simple commands
 Home-page: https://github.com/InzamamulQureshi/Codefetch
 Author: Inzamamul Qureshi
@@ -24,7 +24,7 @@ Dynamic: requires-python
 
 Quickly fetch code files from GitHub repositories with simple commands.
 
-CodeFetch is a lightweight command-line utility designed to quickly inspect, preview, and download individual source code files directly from any GitHub repository without needing to clone full repositories.
+CodeFetch is a lightweight command-line utility and Python library designed to quickly inspect, preview, and download individual source code files directly from any GitHub repository without needing to clone full repositories.
 
 ---
 
@@ -35,6 +35,7 @@ CodeFetch is a lightweight command-line utility designed to quickly inspect, pre
 - **Automatic Path & Case Resolution**: Automatically resolves case mismatches and finds files nested inside subdirectories.
 - **Repository Discovery**: List all public repositories for any GitHub user with `--repos`.
 - **Tree Exploration**: List all supported code files within a repository with `--list`.
+- **Python Library Support**: Import and use programmatically with `import codefetch as cf`.
 - **Optional Persistent Defaults**: Save a default repository or user with `--set-default` if you frequently work with the same repository.
 - **Zero Runtime Dependencies**: Built using only the Python standard library with zero third-party dependencies.
 
@@ -130,6 +131,28 @@ codefetch --reset-config
 
 ---
 
+## Python API Usage
+
+You can also use CodeFetch programmatically within your Python scripts:
+
+```python
+import codefetch as cf
+
+# 1. Fetch file content as a string directly in memory
+makefile_text = cf.get("torvalds/linux", "Makefile")
+# Or shorthand single argument syntax:
+readme_text = cf.get("psf/requests/README.md")
+
+# 2. Download a file to disk
+cf.download("torvalds/linux", "Makefile", output="linux_Makefile")
+
+# 3. List all code files in a repository
+files = cf.list("torvalds/linux")
+print(f"Found {len(files)} files")
+```
+
+---
+
 ## Command Reference
 
 | Flag | Description | Example |

codefetch_cli-1.2.4.dist-info/RECORD

@@ -0,0 +1,8 @@
+codefetch/__init__.py,sha256=3VbBrolY7csLzdP8QSlksD1iBNJqaEa2CvyZhg_sdYk,5049
+codefetch/cli.py,sha256=uun_VFjFI_B4PPFzKJhPU8IcTrsQY0OuU6nzAYRXIvQ,32190
+codefetch_cli-1.2.4.dist-info/licenses/LICENSE,sha256=hqEPPm8jxPava5BfKIj3wTIXNyWNwsIvPv2daPCOijY,1094
+codefetch_cli-1.2.4.dist-info/METADATA,sha256=a6mkv8w6CLgKRlQTXFb-UAEfdLCJCjhrPpjAtu041Dk,6675
+codefetch_cli-1.2.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+codefetch_cli-1.2.4.dist-info/entry_points.txt,sha256=jFLRsBB_USeSdqjewcXZfnOzY56s0PZat7mnYkYdrXg,49
+codefetch_cli-1.2.4.dist-info/top_level.txt,sha256=kHrftHbyqugb8LQXjW1dR9uI-JFjZQJ0sUReIa45yXQ,10
+codefetch_cli-1.2.4.dist-info/RECORD,,

codefetch_cli-1.2.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-codefetch/__init__.py,sha256=OgTOFFfQIh-gT-X8j2hheukYFmfAe0SvzIuA_LosY6Y,98
-codefetch/cli.py,sha256=muL99Mr9tCPZ0UJp3YfVcVGMxTLvCPGfEbOmH-GpNCU,23588
-codefetch_cli-1.2.2.dist-info/licenses/LICENSE,sha256=hqEPPm8jxPava5BfKIj3wTIXNyWNwsIvPv2daPCOijY,1094
-codefetch_cli-1.2.2.dist-info/METADATA,sha256=pOL04v-tCvJap5vLYlCE9bDXBv768lm-LR5gghvyzlc,6000
-codefetch_cli-1.2.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-codefetch_cli-1.2.2.dist-info/entry_points.txt,sha256=jFLRsBB_USeSdqjewcXZfnOzY56s0PZat7mnYkYdrXg,49
-codefetch_cli-1.2.2.dist-info/top_level.txt,sha256=kHrftHbyqugb8LQXjW1dR9uI-JFjZQJ0sUReIa45yXQ,10
-codefetch_cli-1.2.2.dist-info/RECORD,,