oss-issue-scout 0.2.0__tar.gz

oss_issue_scout-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruifeng Xue
+
+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.

oss_issue_scout-0.2.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: oss-issue-scout
+Version: 0.2.0
+Summary: Find worthwhile open-source issues.
+Author: Ruifeng Xue
+License: MIT License
+        
+        Copyright (c) 2026 Ruifeng Xue
+        
+        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.
+        
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# oss-issue-scout
+
+Find worthwhile open-source issues
+
+The current version calls the GitHub API, searches open issues, and applies a simple score based on repository activity, issue activity, comments, labels, and related signals.
+It is currently aimed at junior to intermediate developers who want a faster way to find approachable issues.
+
+## Features
+
+- Search GitHub open issues
+- Filter by language, label, stars, and update recency
+- Skip issues that already have linked PRs
+- Recommend only unassigned issues by default
+- Skip repositories with fewer than 100 stars by default
+- Render results as `table`, `markdown`, or `json`
+- No third-party dependencies
+
+## Usage
+
+```powershell
+python -m pip install -e .
+oss-issue-scout search --language python --label "good first issue" --limit 5
+```
+
+## Options
+
+```text
+--language            Repository primary language, such as python
+--stars-min           Minimum repository stars; defaults to at least 100
+--label               Issue label, such as "good first issue"
+--updated-days        Issue updated within the last N days
+--repo-updated-days   Repository had issue activity within the last N days
+--limit               Number of results, default 10
+--format              Output format: table, markdown, json
+```
+
+Examples:
+
+```powershell
+oss-issue-scout search --language python
+oss-issue-scout search --language python --label "help wanted" --stars-min 500 --limit 10
+oss-issue-scout search --language python --format json
+oss-issue-scout search --language "C++" --label "good first issue" --repo-updated-days 7
+```
+
+## Scoring
+
+The current score is intentionally simple. It considers:
+
+- Repository stars: moderately active repos get a boost; very large repos may be penalized
+- Issue update recency: recently updated issues get a boost; stale issues are penalized
+- Repository issue activity: recent issue activity gets a boost
+- Beginner-friendly labels: `good first issue` / `help wanted` only add points when the repo has at least 3 open issues with those labels
+- Comment count: low discussion volume gets a boost; long discussions are penalized
+
+The search step filters out:
+
+- Closed issues
+- Archived repositories
+- Issues with linked PRs
+- Assigned issues
+- Repositories with fewer than 100 stars
+
+## Tests
+
+```powershell
+python -m unittest discover
+```
+
+Tests use mocked GitHub responses and do not call the real GitHub API.
+
+## Next
+
+This project is still small. If it helps you, please consider giving it a ⭐. Discussions will be opened after the project reaches 16+ ⭐.
+
+If you have suggestions or run into problems, please open an issue.
+
+Future versions will continue to improve recommendation quality and usability.
+
+## Contributors
+
+<a href="https://github.com/Yong-yuan-X/oss-issue-scout/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Yong-yuan-X/oss-issue-scout" alt="Contributors" />
+</a>

oss_issue_scout-0.2.0/README.en.md

@@ -0,0 +1,84 @@
+# oss-issue-scout
+
+Find worthwhile open-source issues
+
+The current version calls the GitHub API, searches open issues, and applies a simple score based on repository activity, issue activity, comments, labels, and related signals.
+It is currently aimed at junior to intermediate developers who want a faster way to find approachable issues.
+
+## Features
+
+- Search GitHub open issues
+- Filter by language, label, stars, and update recency
+- Skip issues that already have linked PRs
+- Recommend only unassigned issues by default
+- Skip repositories with fewer than 100 stars by default
+- Render results as `table`, `markdown`, or `json`
+- No third-party dependencies
+
+## Usage
+
+```powershell
+python -m pip install -e .
+oss-issue-scout search --language python --label "good first issue" --limit 5
+```
+
+## Options
+
+```text
+--language            Repository primary language, such as python
+--stars-min           Minimum repository stars; defaults to at least 100
+--label               Issue label, such as "good first issue"
+--updated-days        Issue updated within the last N days
+--repo-updated-days   Repository had issue activity within the last N days
+--limit               Number of results, default 10
+--format              Output format: table, markdown, json
+```
+
+Examples:
+
+```powershell
+oss-issue-scout search --language python
+oss-issue-scout search --language python --label "help wanted" --stars-min 500 --limit 10
+oss-issue-scout search --language python --format json
+oss-issue-scout search --language "C++" --label "good first issue" --repo-updated-days 7
+```
+
+## Scoring
+
+The current score is intentionally simple. It considers:
+
+- Repository stars: moderately active repos get a boost; very large repos may be penalized
+- Issue update recency: recently updated issues get a boost; stale issues are penalized
+- Repository issue activity: recent issue activity gets a boost
+- Beginner-friendly labels: `good first issue` / `help wanted` only add points when the repo has at least 3 open issues with those labels
+- Comment count: low discussion volume gets a boost; long discussions are penalized
+
+The search step filters out:
+
+- Closed issues
+- Archived repositories
+- Issues with linked PRs
+- Assigned issues
+- Repositories with fewer than 100 stars
+
+## Tests
+
+```powershell
+python -m unittest discover
+```
+
+Tests use mocked GitHub responses and do not call the real GitHub API.
+
+## Next
+
+This project is still small. If it helps you, please consider giving it a ⭐. Discussions will be opened after the project reaches 16+ ⭐.
+
+If you have suggestions or run into problems, please open an issue.
+
+Future versions will continue to improve recommendation quality and usability.
+
+## Contributors
+
+<a href="https://github.com/Yong-yuan-X/oss-issue-scout/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Yong-yuan-X/oss-issue-scout" alt="Contributors" />
+</a>

oss_issue_scout-0.2.0/README.md

@@ -0,0 +1,86 @@
+# oss-issue-scout
+
+发现值得贡献的开源 issues
+
+[English README](README.en.md)
+
+当前版本会调用 GitHub API 搜索 open issues，并根据项目活跃度、issue 活跃度、评论数量、标签等信号做一个简单评分
+它主要面向初中级开发者，用来快速筛出更可能适合贡献的 issue
+
+## 功能
+
+- 搜索 GitHub open issues
+- 支持按语言、标签、stars、更新时间过滤
+- 默认跳过已有关联 PR 的 issue
+- 默认只推荐未指派的 issue
+- 默认过滤 stars 少于 100 的 repo
+- 支持 `table`、`markdown`、`json` 输出
+- 不依赖第三方包
+
+## 使用
+
+```powershell
+python -m pip install -e .
+oss-issue-scout search --language python --label "good first issue" --limit 5
+```
+
+## 参数
+
+```text
+--language            仓库主要语言，例如 python
+--stars-min           仓库最低 stars，默认至少 100
+--label               issue 标签，例如 "good first issue"
+--updated-days        当前 issue 最近多少天内更新过
+--repo-updated-days   issue 所在 repo 最近多少天内有 issue 活动
+--limit               返回数量，默认 10
+--format              输出格式：table、markdown、json
+```
+
+示例：
+
+```powershell
+oss-issue-scout search --language python
+oss-issue-scout search --language python --label "help wanted" --stars-min 500 --limit 10
+oss-issue-scout search --language python --format json
+oss-issue-scout search --language "C++" --label "good first issue" --repo-updated-days 7
+```
+
+## 推荐规则
+
+当前评分比较简单，主要参考：
+
+- repo stars：中等活跃项目加分，超大型项目可能扣分
+- issue 更新时间：近期更新加分，长期未更新扣分
+- repo issue 活动：近期有 issue 活动加分
+- beginner 标签：当前 issue 有 `good first issue` / `help wanted`，且 repo 中至少有 3 个同类 open issues 时加分
+- 评论数量：评论少加分，讨论过长扣分
+
+搜索阶段会直接排除：
+
+- closed issues
+- archived repos
+- 已 linked PR 的 issues
+- 已指派 assignee 的 issues
+- stars 少于 100 的 repos
+
+## 测试
+
+```powershell
+python -m unittest discover
+```
+
+测试使用 mock 数据，不会请求真实 GitHub API
+
+## 后续
+
+现在项目使用的人还比较少，如果你觉得它对你有帮助，欢迎点一个 ⭐。达到 16+ ⭐ 后会开启 Discussions
+
+如果有改进建议或使用问题，可以在 issues 中提出
+
+后续会逐步进行版本迭代，继续优化推荐质量和使用体验
+
+## 贡献者
+
+<a href="https://github.com/Yong-yuan-X/oss-issue-scout/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Yong-yuan-X/oss-issue-scout" alt="Contributors" />
+</a>

oss_issue_scout-0.2.0/oss_issue_scout/__init__.py

@@ -0,0 +1,3 @@
+"""Find worthwhile open-source issues."""
+
+__version__ = "0.2.0"

oss_issue_scout-0.2.0/oss_issue_scout/cli.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .github_api import GitHubAPIError, search_issues
+from .output import render_results
+from .scoring import score_issues
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="oss-issue-scout")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    search_parser = subparsers.add_parser("search", help="search GitHub issues")
+    search_parser.add_argument("--language")
+    search_parser.add_argument("--stars-min", type=int)
+    search_parser.add_argument("--label")
+    search_parser.add_argument("--updated-days", type=int)
+    search_parser.add_argument("--repo-updated-days", type=int)
+    search_parser.add_argument("--limit", type=_positive_int, default=10)
+    search_parser.add_argument(
+        "--format",
+        choices=("table", "markdown", "json"),
+        default="table",
+    )
+    search_parser.set_defaults(func=_run_search)
+    return parser
+
+
+def _positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("must be greater than 0")
+    return parsed
+
+
+def _run_search(args: argparse.Namespace) -> int:
+    try:
+        issues = search_issues(
+            language=args.language,
+            stars_min=args.stars_min,
+            label=args.label,
+            updated_days=args.updated_days,
+            repo_updated_days=args.repo_updated_days,
+            limit=args.limit,
+        )
+    except GitHubAPIError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    results = score_issues(issues)[: args.limit]
+    print(render_results(results, args.format))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

oss_issue_scout-0.2.0/oss_issue_scout/github_api.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode
+from urllib.request import Request, urlopen
+
+
+GITHUB_API_BASE = "https://api.github.com"
+GITHUB_API_VERSION = "2026-03-10"
+DEFAULT_STARS_MIN = 100
+MAX_SEARCH_PAGES = 5
+
+
+class GitHubAPIError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Issue:
+    repo: str
+    title: str
+    url: str
+    language: str
+    stars: int
+    labels: tuple[str, ...]
+    updated_days: int
+    repo_last_issue_updated_days: int
+    repo_beginner_issue_count: int
+    comments: int
+    has_open_pr: bool
+
+
+def search_issues(
+    *,
+    language: str | None = None,
+    stars_min: int | None = None,
+    label: str | None = None,
+    updated_days: int | None = None,
+    repo_updated_days: int | None = None,
+    limit: int = 10,
+) -> list[Issue]:
+    if limit <= 0:
+        return []
+
+    effective_stars_min = max(stars_min or DEFAULT_STARS_MIN, DEFAULT_STARS_MIN)
+
+    query = _build_issue_query(
+        language=language,
+        stars_min=effective_stars_min,
+        label=label,
+        updated_days=updated_days,
+    )
+    repo_cache: dict[str, dict[str, Any]] = {}
+    repo_activity_cache: dict[str, int] = {}
+    repo_beginner_issue_count_cache: dict[str, int] = {}
+    issues: list[Issue] = []
+    # Search candidates match the GitHub query first, then local filters below
+    # enforce repo metadata and repo activity rules.
+    per_page = min(max(limit * 10, 30), 100)
+
+    for page in range(1, MAX_SEARCH_PAGES + 1):
+        data = _request_json(
+            "/search/issues",
+            {
+                "q": query,
+                "sort": "updated",
+                "order": "desc",
+                "per_page": str(per_page),
+                "page": str(page),
+            },
+        )
+        items = data.get("items", [])
+        if not items:
+            break
+
+        for item in items:
+            if "pull_request" in item:
+                continue
+
+            repo = _repo_full_name(item)
+            if repo is None:
+                continue
+
+            if repo not in repo_cache:
+                repo_cache[repo] = _repo_info_from_search_result(item) or _get_repo(repo)
+            repo_info = repo_cache[repo]
+            stars = int(repo_info.get("stargazers_count") or 0)
+            if stars < effective_stars_min:
+                continue
+
+            repo_language = str(repo_info.get("language") or "")
+            if language and repo_language.casefold() != language.casefold():
+                continue
+
+            if repo not in repo_activity_cache:
+                repo_activity_cache[repo] = _get_repo_last_issue_updated_days(repo)
+            if repo not in repo_beginner_issue_count_cache:
+                repo_beginner_issue_count_cache[repo] = _get_repo_beginner_issue_count(repo)
+            if (
+                repo_updated_days is not None
+                and repo_activity_cache[repo] > repo_updated_days
+            ):
+                continue
+
+            issue = Issue(
+                repo=repo,
+                title=str(item.get("title") or ""),
+                url=str(item.get("html_url") or ""),
+                language=repo_language,
+                stars=stars,
+                labels=_labels(item),
+                updated_days=_days_since(str(item.get("updated_at") or "")),
+                repo_last_issue_updated_days=repo_activity_cache[repo],
+                repo_beginner_issue_count=repo_beginner_issue_count_cache[repo],
+                comments=int(item.get("comments") or 0),
+                has_open_pr=False,
+            )
+            issues.append(issue)
+            if len(issues) >= limit:
+                break
+
+        if len(issues) >= limit or len(items) < per_page:
+            break
+
+    return issues
+
+
+def _build_issue_query(
+    *,
+    language: str | None,
+    stars_min: int | None,
+    label: str | None,
+    updated_days: int | None,
+) -> str:
+    parts = ["is:issue", "is:open", "archived:false", "-linked:pr", "no:assignee"]
+    if language:
+        parts.append(f"language:{_quote_query_value(language)}")
+    if label:
+        parts.append(f"label:{_quote_query_value(label)}")
+    if updated_days is not None:
+        cutoff = datetime.now(timezone.utc).date() - timedelta(days=updated_days)
+        parts.append(f"updated:>={cutoff.isoformat()}")
+    return " ".join(parts)
+
+
+def _request_json(path: str, params: dict[str, str] | None = None) -> dict[str, Any]:
+    url = f"{GITHUB_API_BASE}{path}"
+    if params:
+        url = f"{url}?{urlencode(params)}"
+
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": GITHUB_API_VERSION,
+        "User-Agent": "oss-issue-scout",
+    }
+    token = os.environ.get("GITHUB_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    request = Request(url, headers=headers)
+    try:
+        with urlopen(request, timeout=20) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except HTTPError as error:
+        message = error.read().decode("utf-8", errors="replace")
+        if error.code == 403 and "rate limit" in message.casefold():
+            raise GitHubAPIError(
+                "GitHub API rate limit exceeded. Set a GITHUB_TOKEN environment "
+                "variable to get a higher rate limit, then try again."
+            ) from error
+        raise GitHubAPIError(f"GitHub API request failed: HTTP {error.code} {message}") from error
+    except URLError as error:
+        raise GitHubAPIError(f"GitHub API request failed: {error.reason}") from error
+
+
+def _get_repo(repo: str) -> dict[str, Any]:
+    owner, name = repo.split("/", 1)
+    return _request_json(f"/repos/{quote(owner)}/{quote(name)}")
+
+
+def _get_repo_last_issue_updated_days(repo: str) -> int:
+    data = _request_json(
+        "/search/issues",
+        {
+            "q": f"repo:{repo} is:issue",
+            "sort": "updated",
+            "order": "desc",
+            "per_page": "1",
+        },
+    )
+    items = data.get("items", [])
+    if not items:
+        return 9999
+    return _days_since(str(items[0].get("updated_at") or ""))
+
+
+def _get_repo_beginner_issue_count(repo: str) -> int:
+    data = _request_json(
+        "/search/issues",
+        {
+            "q": f'repo:{repo} is:issue is:open label:"good first issue","help wanted"',
+            "per_page": "1",
+        },
+    )
+    return int(data.get("total_count") or 0)
+
+
+def _repo_full_name(item: dict[str, Any]) -> str | None:
+    repository_url = str(item.get("repository_url") or "")
+    marker = f"{GITHUB_API_BASE}/repos/"
+    if repository_url.startswith(marker):
+        return repository_url.removeprefix(marker)
+    repository = item.get("repository")
+    if isinstance(repository, dict):
+        full_name = repository.get("full_name")
+        if isinstance(full_name, str):
+            return full_name
+    return None
+
+
+def _repo_info_from_search_result(item: dict[str, Any]) -> dict[str, Any] | None:
+    repository = item.get("repository")
+    if not isinstance(repository, dict):
+        return None
+    if "stargazers_count" not in repository or "language" not in repository:
+        return None
+    return repository
+
+
+def _labels(item: dict[str, Any]) -> tuple[str, ...]:
+    labels = item.get("labels") or []
+    names: list[str] = []
+    for label in labels:
+        if isinstance(label, dict) and isinstance(label.get("name"), str):
+            names.append(label["name"])
+    return tuple(names)
+
+
+def _days_since(value: str) -> int:
+    if not value:
+        return 9999
+    timestamp = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    delta = datetime.now(timezone.utc) - timestamp
+    return max(delta.days, 0)
+
+
+def _quote_query_value(value: str) -> str:
+    if " " in value:
+        return f'"{value}"'
+    return value