afwf_github 1.0.1__py3-none-any.whl

afwf_github/__init__.py

@@ -0,0 +1 @@
+# -*- coding: utf-8 -*-

afwf_github/api.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+

afwf_github/cache.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+
+"""
+Factory for diskcache instances used to store GitHub API responses.
+
+Each GitHub user gets their own cache directory under their per-user data
+directory. sayt2 datasets manage their own internal search result cache
+separately — this module only covers GitHub API response caching.
+"""
+
+from pathlib import Path
+
+from diskcache import Cache
+
+
+def make_cache(dir_cache: Path) -> Cache:
+    """Create a ``diskcache.Cache`` at *dir_cache*.
+
+    diskcache creates the directory if it does not exist, so callers do not
+    need to ensure the path exists beforehand.
+    """
+    return Cache(dir_cache)

afwf_github/cli.py

@@ -0,0 +1,295 @@
+# -*- coding: utf-8 -*-
+
+import sys
+import json
+import typing as T
+import functools
+from pathlib import Path
+from functools import cached_property
+
+import fire
+import afwf.api as afwf
+import git_web_url.api as gwu
+from git_web_url.exc import NotGitRepoError
+
+from .config import Config
+from .paths import path_enum
+from .dataset import create_repo_dataset
+
+_CONFIG_TEMPLATE = {
+    "pac_token": None,
+    "pac_token_home_secret_toml_path": None,
+    "cache_expire": 2_592_000,
+}
+
+_log_error = afwf.log_error(
+    log_file=path_enum.path_error_log,
+    tb_limit=10,
+)
+
+
+def _error_sf(exc: Exception) -> afwf.ScriptFilter:
+    item = afwf.Item(
+        title=f"{type(exc).__name__}: {exc}",
+        subtitle=f"Press Enter to open the error log: {path_enum.path_error_log}",
+        icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.error),
+        valid=True,
+    )
+    item.open_file(str(path_enum.path_error_log))
+    return afwf.ScriptFilter(items=[item])
+
+
+def _config_error_sf(config_path: Path) -> afwf.ScriptFilter:
+    item = afwf.Item(
+        title=f"Config file not found: {config_path}",
+        subtitle="Press Enter to open the setup guide on GitHub",
+        icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.error),
+        valid=True,
+    )
+    item.open_url("https://github.com/MacHu-GWU/afwf_github-project")
+    return afwf.ScriptFilter(items=[item])
+
+
+def require_config(method: T.Callable) -> T.Callable:
+    """Decorator that resolves and loads config before calling a CLI method.
+
+    Resolution order:
+    1. If ``self.config_file`` is set, load from that path.
+    2. Otherwise use the default path (``path_enum.path_config_json``).
+
+    On any failure (file missing, parse error) the decorator outputs a
+    single error ``Item`` that opens the project README on Enter, then
+    returns early so the wrapped method is never called.
+
+    On success, ``self._config`` is populated and the wrapped method runs
+    normally.
+
+    ``functools.wraps`` is still required in Python 3.10+ to copy
+    ``__name__``, ``__doc__``, ``__wrapped__``, etc. onto the wrapper —
+    ``ParamSpec`` (added in 3.10) improves type-checker inference for
+    decorators but does not replace ``functools.wraps``.
+    """
+
+    @functools.wraps(method)
+    def wrapper(self: "Command", *args, **kwargs):
+        if self.config_file is not None:
+            config_path = Path(self.config_file).expanduser().resolve()
+        else:
+            config_path = path_enum.path_config_json
+
+        if not config_path.exists():
+            _config_error_sf(config_path).send_feedback()
+            return
+
+        try:
+            self._config = Config.load(config_path)
+        except Exception:
+            _config_error_sf(config_path).send_feedback()
+            return
+
+        return method(self, *args, **kwargs)
+
+    return wrapper
+
+
+class Command:
+    """Alfred GitHub Workflow CLI.
+
+    All subcommands accept an optional ``--config-file`` argument (absolute
+    or relative path).  When omitted, config is loaded from the default
+    location via ``default_config``.
+    """
+
+    def __init__(self, config_file: str | None = None):
+        self.config_file = config_file
+        self._config: Config | None = None
+
+    @cached_property
+    def default_config(self) -> Config:
+        """Load config from the default path (``~/.alfred-afwf/afwf_github/config.json``)."""
+        return Config.load(path_enum.path_config_json)
+
+    @afwf.log_error(
+
+    )
+    def edit_config(self) -> None:
+        """Script Filter: open config.json in the default editor.
+
+        Creates a blank template at the default path if the file does not yet
+        exist, then opens it via Alfred's Open File action.
+
+        Alfred Script field (dev):
+            .venv/bin/afwf-github edit-config
+
+        Alfred Script field (prod):
+            ~/.local/bin/uvx --from afwf_github==<ver> afwf-github edit-config
+        """
+        @_log_error
+        def _run():
+            config_path = path_enum.path_config_json
+            if not config_path.exists():
+                config_path.parent.mkdir(parents=True, exist_ok=True)
+                config_path.write_text(json.dumps(_CONFIG_TEMPLATE, indent=4))
+            item = afwf.Item(
+                title="Open and edit config.json",
+                subtitle=str(config_path),
+                icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.file),
+            )
+            item.open_file(str(config_path))
+            afwf.ScriptFilter(items=[item]).send_feedback()
+
+        try:
+            _run()
+        except Exception as e:
+            _error_sf(e).send_feedback()
+
+    @require_config
+    def view_in_browser(self, path: str = "") -> None:
+        """Script Filter: given a local file or directory path, open its GitHub URL in the browser.
+
+        Alfred Script field (dev):
+            .venv/bin/afwf-github view-in-browser --path '{query}'
+
+        Alfred Script field (prod):
+            ~/.local/bin/uvx --from afwf_github==<ver> afwf-github view-in-browser --path '{query}'
+        """
+        @_log_error
+        def _run():
+            if not path.strip():
+                afwf.ScriptFilter(
+                    items=[
+                        afwf.Item(
+                            title="Type or paste the absolute path of a local file or directory"
+                        )
+                    ]
+                ).send_feedback()
+                return
+
+            try:
+                url = gwu.get_web_url(Path(path))
+                item = afwf.Item(
+                    title=f"Open in browser: {url}",
+                    subtitle=f"Local path: {path}",
+                    icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.internet),
+                )
+                item.open_url(url)
+            except NotGitRepoError:
+                item = afwf.Item(
+                    title=f"Not a git repository path: {path}",
+                    subtitle="Only paths inside a git repo with a remote can be opened in browser",
+                    icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.error),
+                    valid=False,
+                )
+
+            afwf.ScriptFilter(items=[item]).send_feedback()
+
+        try:
+            _run()
+        except Exception as e:
+            _error_sf(e).send_feedback()
+
+    @require_config
+    def search_repo(self, query: str = "") -> None:
+        """Script Filter: search GitHub repositories in the local index.
+
+        Alfred Script field (dev):
+            .venv/bin/afwf-github search-repo --query '{query}'
+
+        Alfred Script field (prod):
+            ~/.local/bin/uvx --from afwf_github==<ver> afwf-github search-repo --query '{query}'
+        """
+        @_log_error
+        def _run():
+            if not query.strip():
+                afwf.ScriptFilter(
+                    items=[afwf.Item(title="Type to search GitHub repositories ...")]
+                ).send_feedback()
+                return
+
+            dataset = create_repo_dataset(config=self._config)
+            result = dataset.search(query=query, limit=50)
+
+            if not result.hits:
+                afwf.ScriptFilter(
+                    items=[
+                        afwf.Item(
+                            title=f"No repository found for: {query!r}",
+                            icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.error),
+                            valid=False,
+                        )
+                    ]
+                ).send_feedback()
+                return
+
+            items = []
+            for hit in result.hits:
+                repo = hit.source
+                account_name = repo["acc"]
+                repo_name = repo["repo"]
+                repo_description = repo.get("desc", "No description")
+                url = f"https://github.com/{account_name}/{repo_name}"
+                item = afwf.Item(
+                    title=f"{account_name}/{repo_name}",
+                    subtitle=repo_description,
+                    autocomplete=f"{account_name}/{repo_name}",
+                )
+                item.open_url(url)
+                items.append(item)
+            afwf.ScriptFilter(items=items).send_feedback()
+
+        try:
+            _run()
+        except Exception as e:
+            _error_sf(e).send_feedback()
+
+    @require_config
+    def rebuild_index(self) -> None:
+        """Script Filter: show a single item that triggers ``rebuild-index-action`` on Enter.
+
+        Alfred Script field (dev):
+            .venv/bin/afwf-github rebuild-index
+
+        Alfred Script field (prod):
+            ~/.local/bin/uvx --from afwf_github==<ver> afwf-github rebuild-index
+        """
+        @_log_error
+        def _run():
+            bin_cli = Path(sys.executable).parent / "afwf-github"
+            cmd = f"{bin_cli} rebuild-index-action"
+            if self.config_file is not None:
+                cmd += f" --config-file {self.config_file!r}"
+
+            item = afwf.Item(
+                title="Rebuild Index for GitHub Alfred Workflow",
+                subtitle="Hit Enter to rebuild — may take 10–20 seconds",
+                icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.reset),
+            )
+            item.run_script(cmd)
+            afwf.ScriptFilter(items=[item]).send_feedback()
+
+        try:
+            _run()
+        except Exception as e:
+            _error_sf(e).send_feedback()
+
+    @require_config
+    @_log_error
+    def rebuild_index_action(self) -> None:
+        """Rebuild the local repo search index by re-fetching data from GitHub.
+
+        Called by Alfred's Run Script widget — NOT a Script Filter.
+
+        Alfred Run Script field (dev):
+            .venv/bin/afwf-github rebuild-index-action
+
+        Alfred Run Script field (prod):
+            ~/.local/bin/uvx --from afwf_github==<ver> afwf-github rebuild-index-action
+        """
+        create_repo_dataset(config=self._config).search(
+            query="",
+            refresh=True,
+        )
+
+
+def run():
+    fire.Fire(Command)

afwf_github/config.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+
+import json
+from pathlib import Path
+from functools import cached_property
+
+from pydantic import BaseModel, ConfigDict, model_validator
+from github import Github, Auth
+from home_secret_toml.api import hs
+
+from .paths import path_enum
+
+path_config_json = path_enum.path_config_json
+
+
+class Config(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    pac_token: str | None = None
+    pac_token_home_secret_toml_path: str | None = None
+    cache_expire: int = 30 * 24 * 3600
+
+    @model_validator(mode="after")
+    def check_pac_token(self):
+        if self.pac_token is None and self.pac_token_home_secret_toml_path is None:
+            raise ValueError("Must provide pac_token or pac_token_home_secret_toml_path")
+        return self
+
+    @classmethod
+    def load(cls, path: Path) -> "Config":  # pragma: no cover
+        return cls.model_validate(json.loads(path.read_text()))
+
+    def dump(self, path: Path):  # pragma: no cover
+        path.write_text(self.model_dump_json(indent=4))
+
+    @cached_property
+    def gh(self):
+        if self.pac_token is not None:
+            pac_token = self.pac_token
+        elif self.pac_token_home_secret_toml_path is not None:
+            pac_token = hs.v(self.pac_token_home_secret_toml_path)
+        else:
+            raise ValueError("Must provide pac_token or pac_token_home_secret_toml")
+        return Github(auth=Auth.Token(pac_token))

afwf_github/constants.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+
+import enum
+
+
+class CacheKeyEnum(str, enum.Enum):
+    """
+    Cache keys for GitHub data, parameterized by GitHub username.
+
+    Each data type is stored under a separate key (``user@{username}``,
+    ``accounts@{username}``, ``repos@{username}``) rather than a single
+    combined JSON blob. This allows callers to fetch only what they need:
+    reading the authenticated user or listing org accounts is cheap and
+    instantaneous, while fetching all repositories can be slow for accounts
+    with hundreds of repos. Keeping them separate avoids paying the full
+    download cost just to answer a lightweight query.
+    """
+
+    user = "user"
+    """Authenticated GitHub user — id and display name."""
+
+    accounts = "accounts"
+    """All accounts visible to the user: the user themselves plus every org they belong to."""
+
+    repos = "repos"
+    """All repositories accessible to the user across all accounts."""
+
+    def of(self, username: str) -> str:
+        """Return the concrete cache key for a given GitHub username.
+
+        Example::
+
+            >>> CacheKeyEnum.repos.of("alice")
+            'repos@alice'
+        """
+        return f"{self.value}@{username}"

afwf_github/dataset.py

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+
+"""
+Github repo dataset related
+"""
+
+import typing as T
+from pathlib import Path
+
+from diskcache import Cache
+from github import Github
+from sayt2.api import DataSet, NgramField, TextField
+
+from .type_hint import T_RECORD
+from .paths import path_enum
+from .cache import make_cache
+from .config import Config
+from .constants import CacheKeyEnum
+from .github import download_data, get_repos, get_username
+
+repo_fields = [
+    NgramField(name="acc", min_gram=2, max_gram=10, boost=1.0),
+    NgramField(name="repo", min_gram=2, max_gram=10, boost=2.0),
+    TextField(name="desc"),
+]
+
+
+def make_repo_dataset(
+    dir_user: Path,
+    downloader: T.Callable[[], list[T_RECORD]],
+    cache_expire: int,
+) -> DataSet:
+    """
+    Low-level DataSet constructor. Pure function — no GitHub or config
+    dependencies. The caller is responsible for providing the per-user
+    directory, a ready-made downloader, and the cache expiry.
+    """
+    return DataSet(
+        dir_root=dir_user,
+        name="repo",
+        fields=repo_fields,
+        downloader=downloader,
+        cache_expire=cache_expire,
+    )
+
+
+def make_downloader(
+    gh: Github,
+    cache: Cache,
+    username: str,
+    cache_expire: int,
+) -> T.Callable[[], list[T_RECORD]]:  # pragma: no cover
+    """
+    Build the downloader callable used by the repo DataSet.
+
+    Wraps :func:`~afwf_github.github.download_data` with a cache-check:
+    if repos are already stored under the per-user cache key, they are
+    returned directly without hitting the GitHub API.
+    """
+
+    def downloader() -> list[T_RECORD]:
+        cache_key = CacheKeyEnum.repos.of(username)
+        try:
+            repos = get_repos(cache, username) if cache_key in cache else None
+        except FileNotFoundError:
+            # per-user directory was deleted after cache was opened;
+            # fall through to re-download
+            repos = None
+
+        if repos is None:
+            _, _, repos = download_data(
+                gh=gh,
+                cache=cache,
+                username=username,
+                expire=cache_expire,
+            )
+
+        seen = set()
+        records = []
+        for r in repos:
+            key = (r["acc"], r["repo"])
+            if key not in seen:
+                seen.add(key)
+                records.append({"acc": r["acc"], "repo": r["repo"], "desc": r["desc"]})
+        return records
+
+    return downloader
+
+
+def create_repo_dataset(config: Config) -> DataSet:  # pragma: no cover
+    """
+    High-level factory. Derives the GitHub client, username, per-user
+    directory, and cache entirely from *config*.
+    """
+    gh = config.gh
+    user = get_username(gh)
+    username = user["id"]
+    user_dir = path_enum.dir_user(username)
+    cache = make_cache(user_dir / ".cache")
+    downloader = make_downloader(gh, cache, username, config.cache_expire)
+    return make_repo_dataset(user_dir, downloader, config.cache_expire)

afwf_github/github.py

@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+
+"""
+GitHub data related.
+"""
+
+import typing as T
+import json
+import itertools
+
+from github import Github, GithubException
+from diskcache import Cache
+
+from .constants import CacheKeyEnum
+
+
+class UserType(T.TypedDict):
+    id: str
+    name: str
+
+
+class AccountType(T.TypedDict):
+    id: str
+    name: str
+
+
+class RepoType(T.TypedDict):
+    acc: str
+    repo: str
+    desc: str
+
+
+def get_username(gh: Github) -> UserType:
+    """Return the id and display name for the authenticated GitHub user.
+
+    This is a single lightweight API call used to determine the per-user
+    data directory before any heavier operations run.
+    ``id`` is the GitHub login (used for directory names and cache keys);
+    ``name`` is the human-readable display name.
+    """
+    try:
+        gh_user = gh.get_user()
+        user_id: str = gh_user.html_url.split("/")[-1]
+        user_name: str = gh_user.name or user_id
+        return UserType(id=user_id, name=user_name)
+    except GithubException as e:
+        raise RuntimeError(
+            f"Failed to get GitHub username (status={e.status}): {e.data}"
+        ) from e
+    except Exception as e:
+        raise RuntimeError(f"Unexpected error getting GitHub username: {e}") from e
+
+
+def take(iterable: T.Iterable, n: int) -> list:
+    """
+    Return first n items of the iterable as a list.
+
+    Example::
+
+        >>> take([0, 1, 2], 2)
+        [0, 1]
+    """
+    return list(itertools.islice(iterable, n))
+
+
+def fetch_data(
+    gh: Github,
+    page_limit: int = 9999,
+    verbose: bool = False,
+) -> tuple[
+    UserType,
+    list[AccountType],
+    list[RepoType],
+]:  # pragma: no cover
+    """
+    Pull user, accounts, and repos from the GitHub API. No caching.
+    Each API call is treated as potentially failing and raises a descriptive
+    RuntimeError on unexpected errors. 403 responses on individual orgs or
+    repos are silently skipped — the user simply lacks permission for those.
+    """
+    try:
+        gh_user = gh.get_user()
+        user_id: str = gh_user.html_url.split("/")[-1]
+        user_name: str = gh_user.name or user_id
+    except GithubException as e:
+        raise RuntimeError(
+            f"Failed to fetch authenticated user from GitHub (status={e.status}): {e.data}"
+        ) from e
+    except Exception as e:
+        raise RuntimeError(f"Unexpected error fetching authenticated user: {e}") from e
+
+    if verbose:
+        print(f"Fetched user: {user_name} ({user_id})")
+
+    accounts: list[AccountType] = [AccountType(id=user_id, name=user_name)]
+    for org in take(gh_user.get_orgs(), page_limit):
+        try:
+            account_id: str = org.html_url.split("/")[-1]
+            account_name: str = org.name or account_id
+            if verbose:
+                print(f"Fetched org: {account_name} ({account_id})")
+            accounts.append(AccountType(id=account_id, name=account_name))
+        except GithubException as e:
+            if e.status == 403:
+                if verbose:
+                    print(f"Skipped org (no permission, status=403): {e.data}")
+            else:
+                raise RuntimeError(
+                    f"Failed to fetch org details (status={e.status}): {e.data}"
+                ) from e
+        except Exception as e:
+            raise RuntimeError(f"Unexpected error fetching org: {e}") from e
+
+    repos: list[RepoType] = []
+    for repo in take(gh_user.get_repos(visibility="all"), page_limit):
+        try:
+            account_name = repo.full_name.split("/")[0]
+            repo_name: str = repo.name
+            repo_desc: str = repo.description or ""
+            if verbose:
+                print(f"Fetched repo: {account_name}/{repo_name}")
+            repos.append(RepoType(acc=account_name, repo=repo_name, desc=repo_desc))
+        except GithubException as e:
+            if e.status == 403:
+                if verbose:
+                    print(f"Skipped repo (no permission, status=403): {e.data}")
+            else:
+                raise RuntimeError(
+                    f"Failed to fetch repo details (status={e.status}): {e.data}"
+                ) from e
+        except Exception as e:
+            raise RuntimeError(f"Unexpected error fetching repo: {e}") from e
+
+    user: UserType = UserType(id=user_id, name=user_name)
+    return user, accounts, repos
+
+
+def download_data(
+    gh: Github,
+    cache: Cache,
+    username: str,
+    expire: int,
+    page_limit: int = 9999,
+    verbose: bool = False,
+) -> tuple[
+    UserType,
+    list[AccountType],
+    list[RepoType],
+]:  # pragma: no cover
+    """
+    Pull data from GitHub via :func:`fetch_data` and store results in cache
+    under per-username keys (e.g. ``repos@alice``).
+    """
+    user, accounts, repos = fetch_data(gh, page_limit=page_limit, verbose=verbose)
+    cache.set(CacheKeyEnum.user.of(username), json.dumps(user), expire=expire)
+    cache.set(CacheKeyEnum.accounts.of(username), json.dumps(accounts), expire=expire)
+    cache.set(CacheKeyEnum.repos.of(username), json.dumps(repos), expire=expire)
+    return user, accounts, repos
+
+
+def get_user(
+    cache: Cache,
+    username: str,
+) -> UserType:
+    return json.loads(cache.get(CacheKeyEnum.user.of(username)))
+
+
+def get_accounts(
+    cache: Cache,
+    username: str,
+) -> list[AccountType]:
+    return json.loads(cache.get(CacheKeyEnum.accounts.of(username)))
+
+
+def get_repos(
+    cache: Cache,
+    username: str,
+) -> list[RepoType]:
+    return json.loads(cache.get(CacheKeyEnum.repos.of(username)))

afwf_github/paths.py

@@ -0,0 +1,93 @@
+# -*- coding: utf-8 -*-
+
+from pathlib import Path
+from functools import cached_property
+
+_dir_here = Path(__file__).absolute().parent
+PACKAGE_NAME = _dir_here.name
+
+
+class PathEnum:
+    """
+    Centralized enumeration of all project paths with absolute path references.
+
+    Provides IDE-autocomplete-friendly access to all project directories and files using
+    absolute paths to eliminate current directory dependencies and ensure consistent path
+    resolution across different execution contexts and DevOps workflows.
+    """
+    @cached_property
+    def dir_home(self):
+        return Path.home()
+
+    dir_project_root = _dir_here.parent
+    dir_tmp = dir_project_root / "tmp"
+
+    # Source Code
+    dir_package = _dir_here
+    path_version_py = dir_package / "_version.py"
+    path_pyproject_toml = dir_project_root / "pyproject.toml"
+    path_requirements_txt = dir_project_root / "requirements.txt"
+    path_authors = dir_project_root / "AUTHORS.txt"
+    path_license = dir_project_root / "LICENSE.txt"
+    path_release_history = dir_project_root / "release-history.rst"
+
+    # Virtual Environment
+    dir_venv = dir_project_root / ".venv"
+    dir_venv_bin = dir_venv / "bin"
+    path_venv_bin_pip = dir_venv_bin / "pip"
+    path_venv_bin_python = dir_venv_bin / "python"
+    path_venv_bin_pytest = dir_venv_bin / "pytest"
+    path_python_interpreter = path_venv_bin_python
+
+    # Test
+    dir_htmlcov = dir_project_root / "htmlcov"
+    path_cov_index_html = dir_htmlcov / "index.html"
+    dir_unit_test = dir_project_root / "tests"
+    dir_int_test = dir_project_root / "tests_int"
+    dir_load_test = dir_project_root / "tests_load"
+
+    # Documentation
+    dir_docs_source = dir_project_root / "docs" / "source"
+    dir_docs_build_html = dir_project_root / "docs" / "build" / "html"
+
+    # Build
+    dir_build = dir_project_root / "build"
+    dir_dist = dir_project_root / "dist"
+
+    # Alfred workflow runtime paths
+    @cached_property
+    def dir_project_home(self):
+        p = self.dir_home / ".alfred-afwf" / PACKAGE_NAME
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @cached_property
+    def path_config_json(self):
+        return self.dir_project_home / "config.json"
+
+    @cached_property
+    def path_error_log(self):
+        return self.dir_project_home / "error.log"
+
+    def dir_user(self, username: str) -> Path:
+        """Per-user data directory for a specific GitHub account.
+
+        All GitHub API cache and search index for this user live under this
+        directory. Deleting it resets everything for that user cleanly.
+
+        Layout::
+
+            $HOME/.alfred-afwf/afwf_github/{username}/
+              .cache/          # diskcache — GitHub API responses
+              repo/            # sayt2 search dataset (index + query cache)
+        """
+        p = self.dir_project_home / username
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+
+
+path_enum = PathEnum()
+"""
+Single entry point for all project paths with absolute path references.
+"""

afwf_github/type_hint.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+
+import typing as T
+
+T_RECORD = dict[str, T.Any]

afwf_github/vendor/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+

afwf_github/vendor/pytest_cov_helper.py

@@ -0,0 +1,148 @@
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+import contextlib
+import subprocess
+from pathlib import Path
+
+__version__ = "0.2.1"
+
+
+@contextlib.contextmanager
+def temp_cwd(path: Path):
+    """
+    Temporarily set the current working directory (CWD) and automatically
+    switch back when it's done.
+    """
+    cwd = os.getcwd()
+    os.chdir(str(path))
+    try:
+        yield path
+    finally:
+        os.chdir(cwd)
+
+
+def run_unit_test(
+    script: str,
+    root_dir: str,
+):
+    """
+    Run ``pytest -s --tb=native /path/to/script.py`` Command.
+
+    :param script: the path to test script
+    :param root_dir: the dir you want to temporarily set as cwd
+    """
+    bin_pytest = Path(sys.executable).parent / "pytest"
+    args = [
+        f"{bin_pytest}",
+        "-s",
+        "--tb=native",
+        script,
+    ]
+    with temp_cwd(Path(root_dir)):
+        subprocess.run(args)
+
+
+def run_cov_test(
+    script: str,
+    module: str,
+    root_dir: str,
+    htmlcov_dir: str,
+    preview: bool = False,
+    is_folder: bool = False,
+):
+    """
+    The pytest-cov plugin gives you the coverage for entire project. What if
+    I want run per-module test independently and get per-module coverage?
+
+    This is a simple wrapper around pytest + coverage cli command. Allow you to run
+    coverage test from Python script and set the code coverage measurement scope.
+
+    Usage example:
+
+    suppose you have a source code folder structure like this::
+
+        /dir_git_repo/
+        /dir_git_repo/my_library
+        /dir_git_repo/my_library/__init__.py
+        /dir_git_repo/my_library/module1.py
+        /dir_git_repo/my_library/module2.py
+
+    In your module 1 unit test script, you can do this:
+
+    .. code-block:: python
+
+        from my_library.module1 import func1, func2
+
+        def test_func1():
+            pass
+
+        def test_func2():
+            pass
+
+        if __name__ == "__main__":
+            from fixa.pytest_cov_helper import run_cov_test
+
+            run_cov_test(
+                script=__file__,
+                module="my_library.module1", # test scope is the module1.py
+                root_dir="/path/to/dir_git_repo",
+                htmlcov_dir="/path/to/dir_git_repo/htmlcov",
+            )
+
+    In your all modules unit test script, you can do this:
+
+    .. code-block:: python
+
+        if __name__ == "__main__":
+            from fixa.pytest_cov_helper import run_cov_test
+
+            run_cov_test(
+                script=__file__,
+                module="my_library", # test scope is the my_library/
+                root_dir="/path/to/dir_git_repo",
+                htmlcov_dir="/path/to/dir_git_repo/htmlcov",
+                is_folder=True, # my_library is a folder
+            )
+
+    :param script: the test script absolute path
+    :param module: the dot notation to the python module you want to calculate
+        coverage
+    :param root_dir: the dir to dump coverage results binary file
+    :param htmlcov_dir: the dir to dump HTML output
+    :param preview: whether to open the HTML output in web browser after the test
+    :param is_folder: whether the module is a folder
+
+    Reference:
+
+    - https://pypi.org/project/pytest-cov/
+    """
+    bin_pytest = Path(sys.executable).parent / "pytest"
+    if is_folder:
+        script = f"{Path(script).parent}"
+    if module.endswith(".py"):  # pragma: no cover
+        module = module[:-3]
+    args = [
+        f"{bin_pytest}",
+        "-s",
+        "--tb=native",
+        f"--rootdir={root_dir}",
+        f"--cov={module}",
+        "--cov-report",
+        "term-missing",
+        "--cov-report",
+        f"html:{htmlcov_dir}",
+        script,
+    ]
+    with temp_cwd(Path(root_dir)):
+        subprocess.run(args)
+    if preview:  # pragma: no cover
+        platform = sys.platform
+        if platform in ["win32", "cygwin"]:
+            open_command = "start"
+        elif platform in ["darwin", "linux"]:
+            open_command = "open"
+        else:
+            raise NotImplementedError
+        subprocess.run([open_command, f"{Path(htmlcov_dir).joinpath('index.html')}"])

afwf_github-1.0.1.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: afwf_github
+Version: 1.0.1
+Summary: Alfred GitHub Workflow.
+Author-email: Sanhe Hu <husanhe@email.com>
+Maintainer-email: Sanhe Hu <husanhe@email.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MacHu-GWU/afwf_github-project
+Project-URL: Documentation, https://afwf-github.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/MacHu-GWU/afwf_github-project
+Project-URL: Issues, https://github.com/MacHu-GWU/afwf_github-project/issues
+Project-URL: Changelog, https://github.com/MacHu-GWU/afwf_github-project/blob/main/release-history.rst
+Project-URL: Download, https://pypi.org/pypi/afwf-github#files
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+License-File: AUTHORS.rst
+Requires-Dist: pydantic<3.0.0,>=2.11.10
+Requires-Dist: afwf<2.0.0,>=1.0.2
+Requires-Dist: diskcache<6.0.0,>=5.6.3
+Requires-Dist: PyGithub<3.0.0,>=2.8.1
+Requires-Dist: git-web-url<2.0.0,>=1.0.2
+Requires-Dist: sayt2<1.0.0,>=0.1.2
+Requires-Dist: home-secret-toml<1.0.0,>=0.2.1
+Requires-Dist: fire<1.0.0,>=0.6.0
+Provides-Extra: dev
+Requires-Dist: rich<15.0.0,>=13.8.1; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest<9.0.0,>=8.2.2; extra == "test"
+Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == "test"
+Provides-Extra: doc
+Requires-Dist: Sphinx<8.0.0,>=7.4.7; extra == "doc"
+Requires-Dist: sphinx-copybutton<1.0.0,>=0.5.2; extra == "doc"
+Requires-Dist: sphinx-design<1.0.0,>=0.6.1; extra == "doc"
+Requires-Dist: sphinx-jinja<3.0.0,>=2.0.2; extra == "doc"
+Requires-Dist: furo==2024.8.6; extra == "doc"
+Requires-Dist: pygments<3.0.0,>=2.18.0; extra == "doc"
+Requires-Dist: ipython<8.19.0,>=8.18.1; extra == "doc"
+Requires-Dist: nbsphinx<1.0.0,>=0.8.12; extra == "doc"
+Requires-Dist: rstobj==2.0.0; extra == "doc"
+Requires-Dist: docfly==3.0.3; extra == "doc"
+Provides-Extra: mise
+Requires-Dist: PyGithub<3.0.0,>=2.8.0; extra == "mise"
+Requires-Dist: httpx<1.0.0,>=0.28.0; extra == "mise"
+Requires-Dist: tomli<3.0.0,>=2.0.0; python_version < "3.11" and extra == "mise"
+Dynamic: license-file
+
+
+.. image:: https://readthedocs.org/projects/afwf-github/badge/?version=latest
+    :target: https://afwf-github.readthedocs.io/en/latest/
+    :alt: Documentation Status
+
+.. image:: https://github.com/MacHu-GWU/afwf_github-project/actions/workflows/main.yml/badge.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project/actions?query=workflow:CI
+
+.. image:: https://codecov.io/gh/MacHu-GWU/afwf_github-project/branch/main/graph/badge.svg
+    :target: https://codecov.io/gh/MacHu-GWU/afwf_github-project
+
+.. image:: https://img.shields.io/pypi/v/afwf-github.svg
+    :target: https://pypi.python.org/pypi/afwf-github
+
+.. image:: https://img.shields.io/pypi/l/afwf-github.svg
+    :target: https://pypi.python.org/pypi/afwf-github
+
+.. image:: https://img.shields.io/pypi/pyversions/afwf-github.svg
+    :target: https://pypi.python.org/pypi/afwf-github
+
+.. image:: https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github
+    :target: https://github.com/MacHu-GWU/afwf_github-project/blob/main/release-history.rst
+
+.. image:: https://img.shields.io/badge/⭐_Star_me_on_GitHub!--None.svg?style=social&logo=github
+    :target: https://github.com/MacHu-GWU/afwf_github-project
+
+------
+
+.. image:: https://img.shields.io/badge/Link-API-blue.svg
+    :target: https://afwf-github.readthedocs.io/en/latest/py-modindex.html
+
+.. image:: https://img.shields.io/badge/Link-Install-blue.svg
+    :target: `install`_
+
+.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project
+
+.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project/issues
+
+.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project/issues
+
+.. image:: https://img.shields.io/badge/Link-Download-blue.svg
+    :target: https://pypi.org/pypi/afwf-github#files
+
+
+Welcome to ``afwf_github`` Documentation
+==============================================================================
+.. image:: https://afwf-github.readthedocs.io/en/latest/_static/afwf_github-logo.png
+    :target: https://afwf-github.readthedocs.io/en/latest/
+
+It is an `Alfred Workflow <https://www.alfredapp.com/workflows/>`_ for GitHub operations. There already is a PHP `alfred-github-workflow <https://github.com/gharlan/alfred-github-workflow>`_ library for this. But the searching is based on Alfred built-in word level filtering, which doesn't allow any typo, fuzzy, and full text search. This project aims to provide the best searching experience powered by `tantivy <https://github.com/quickwit-oss/tantivy>`_ (via `sayt2 <https://github.com/MacHu-GWU/sayt2-project>`_), a Rust-based full-text search engine.
+
+
+Install
+------------------------------------------------------------------------------
+1. Make sure you have `Alfred 5 + <https://www.alfredapp.com/>`_ installed and bought the `Power Pack <https://www.alfredapp.com/shop/>`_.
+2. Go to `Release <https://github.com/MacHu-GWU/afwf_github-project/releases>`_, download the latest release.
+3. Double click the file to install.
+4. Prepare your GitHub Personal Access Token: go to https://github.com/settings/tokens, create a new token, make sure you checked ``repo -> public_repo``, ``admin:org -> read:org``, ``admin:enterprise -> read:enterprise`` so the workflow can get your public repo name and url information. If you want to get your private repo as well, you should check ``repo (Full control of private repositories)``.
+
+
+Usage
+------------------------------------------------------------------------------
+1. Configuration.
+
+    In Alfred UI, type ``gh-config``, it should open the ~/.alfred-afwf/afwf_github/config.json``
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/2acff3ad-8a90-4326-8f64-3a54df2da11f
+
+2. Build Index
+
+    In Alfred UI, type ``gh-rebuild-index``, it should start to crawl your GitHub repos. It will take a while to finish. You can check the progress in the ``~/.alfred-afwf/afwf_github/.repo_index/``
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/59ce941d-a22a-4fb5-8013-c6a14ec5ca56
+
+3. Search GitHub
+
+    In Alfred UI, type ``gh ${query}``, it should show the following UI:
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/57ea7aa5-d2e0-4b73-8e66-632453418d92
+
+4. Open Git Repo in Browser
+
+    Copy any absolute path of a file in any git repo, type ``gh-view-in-browser ${path}`` then hit ``Enter``, it should open the repo in browser.
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/e863fac8-e9b0-4301-93c0-d745059e4346
+
+
+Trouble Shooting
+------------------------------------------------------------------------------
+1. ``gh ${query}`` doesn't show any result.
+
+    Check the ``${HOME}/.alfred-afwf/afwf_github/`` folder, if there's no folder name equal to your github username(where to store the index), it means the Workflow failed to crawl your GitHub repos. Please double check ``${HOME}/.alfred-afwf/afwf_github/config.json`` to make sure you have the correct GitHub Personal Access Token.

afwf_github-1.0.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+afwf_github/__init__.py,sha256=iwhKnzeBJLKxpRVjvzwiRE63_zNpIBfaKLITauVph-0,24
+afwf_github/api.py,sha256=O9CT1B2F-cVB8elT0EoCJbgkcffjvlmqteqavs4giDg,25
+afwf_github/cache.py,sha256=CZPiNLMh_kJoIz1l1hTNlYt1ilIBNopb_rRkEBEB4vA,627
+afwf_github/cli.py,sha256=aYdSzR3dyGMdug8c0LTx8xEgCugvMFJVDKbrlSKh5NI,9998
+afwf_github/config.py,sha256=_haEkNVekN31YOfQ6DqrmugdagVpv-lN14v15ssSyyY,1419
+afwf_github/constants.py,sha256=q20ww6N_znfLpS7CgaauiWOMrNyTxFVjURHMp1WdvPg,1203
+afwf_github/dataset.py,sha256=0THSggu39cRbwNhmui8gc2XeA3iqE0_nmXeo2Utjggw,2935
+afwf_github/github.py,sha256=llv7seIQ3LFrU08w1Q4DZ8aeebstTO0QHCU-n2JvLqA,5481
+afwf_github/paths.py,sha256=RhRLfkOB7-ObxfjlQjp_4bVQ087YIErDVYjW9dt_u6Y,3018
+afwf_github/type_hint.py,sha256=dNePn5NGiTWH9BNyFuNm09qDEdN9MPG__zVYdUzQY5I,73
+afwf_github/vendor/__init__.py,sha256=O9CT1B2F-cVB8elT0EoCJbgkcffjvlmqteqavs4giDg,25
+afwf_github/vendor/pytest_cov_helper.py,sha256=H2BJtFq3bwJHZtt-bxZ1yF9LnXHVDRZZ0NH-OvkRJdE,4063
+afwf_github-1.0.1.dist-info/licenses/AUTHORS.rst,sha256=oo38V9AD_y57Ac69mKmiItWquV29SRi2aTCdKQo531A,767
+afwf_github-1.0.1.dist-info/licenses/LICENSE.txt,sha256=Fx_tQAmqkcvXayTPbicXlPPrnLKRf1JczCthjVuMS-M,1084
+afwf_github-1.0.1.dist-info/METADATA,sha256=tWj6lMcYK5-rwLg4SqRIHXDkL5KviEfVjJVGhLZ78cA,7826
+afwf_github-1.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+afwf_github-1.0.1.dist-info/entry_points.txt,sha256=ii-KsfGqMcXk9my_QOIm_o3MP60ad9B8VJneBBYhUmk,52
+afwf_github-1.0.1.dist-info/top_level.txt,sha256=pzLhlQvE2dooTdGmz-qQQBMG-f4sJ0_Ob8oE8QqahZ0,12
+afwf_github-1.0.1.dist-info/RECORD,,

afwf_github-1.0.1.dist-info/WHEEL

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

afwf_github-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+afwf-github = afwf_github.cli:run

afwf_github-1.0.1.dist-info/licenses/AUTHORS.rst

@@ -0,0 +1,15 @@
+.. _about_author:
+
+About the Author
+------------------------------------------------------------------------------
+::
+
+   (\ (\
+   ( -.-)o
+   o_(")(")
+
+**Sanhe Hu** is a seasoned software engineer with a deep passion for Python development since 2010. As an author and maintainer of `150+ open-source Python projects <https://pypi.org/user/machugwu/>`_, with over `15 million monthly downloads <https://github.com/MacHu-GWU>`_, I bring a wealth of experience to the table. As a Senior Solution Architect and Subject Matter Expert in AI, Data, Amazon Web Services, Cloud Engineering, DevOps, I thrive on helping clients with platform design, enterprise architecture, and strategic roadmaps.
+
+Talk is cheap, show me the code:
+
+- My Github: https://github.com/MacHu-GWU

afwf_github-1.0.1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanhe Hu <husanhe@email.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

afwf_github-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+afwf_github