dump-github 0.1.8__py3-none-any.whl → 0.2.1__py3-none-any.whl

dump_github/__init__.py

@@ -1,2 +1,4 @@
-# from .lib import *
-from .main import main
+from ._version import __version__
+from .main import main
+
+__all__ = ["__version__", "main"]

dump_github/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.1"

dump_github/lib.py

@@ -1,63 +1,345 @@
-import requests
-
-
-def _github_auth_headers(token):
-    """GitHub REST API expects Authorization: Bearer <token> (PAT classic / fine-grained)."""
-    if not token:
-        return {}
-    token = token.strip()
-    if not token:
-        return {}
-    if token.lower().startswith(("bearer ", "token ", "basic ")):
-        return {"Authorization": token}
-    return {"Authorization": "Bearer {}".format(token)}
-
-
-def get_page_of_repos(username, page, token=""):
-    token_header = _github_auth_headers(token)
-
-    if token_header:
-        url = "https://api.github.com/user/repos?per_page=100&page={}".format(page)
-        headers = {
-            "Accept": "application/vnd.github+json",
-            "X-GitHub-Api-Version": "2022-11-28",
-        }
-        headers.update(token_header)
-        response = requests.get(url, headers=headers)
-        if response.status_code == 200:
-            repos = response.json()
-            return repos
-        else:
-            return []
-    else:
-        url = "https://api.github.com/users/{}/repos?per_page=100&page={}".format(
-            username, page
-        )
-        headers = {
-            "Accept": "application/vnd.github+json",
-            "X-GitHub-Api-Version": "2022-11-28",
-        }
-        response = requests.get(url, headers=headers)
-        if response.status_code == 200:
-            repos = response.json()
-            return repos
-        else:
-            return []
-
-
-def search_user_repos(username, token=""):
-    page = 0
-    res_repos = []
-
-    while True:
-        page += 1
-        repos = get_page_of_repos(username, page, token)
-        if len(repos) == 0:
-            break
-        res_repos += repos
-
-    return res_repos
-
-
-# Backward-compatible alias for the historical typo
-serach_user_repos = search_user_repos
+import re
+import warnings
+from urllib.parse import quote
+
+import requests
+
+GITHUB_API = "https://api.github.com"
+GITHUB_WEB = "https://github.com"
+PER_PAGE = 100
+WEB_USER_AGENT = "dump-github (+https://github.com/Core2002/dump_github)"
+
+
+class GitHubAPIError(RuntimeError):
+    """GitHub could not be read through the REST API (or the web fallback)."""
+
+    def __init__(self, status_code, message):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(message)
+
+
+def _github_auth_headers(token):
+    """GitHub REST API expects Authorization: Bearer <token> (PAT classic / fine-grained)."""
+    if not token:
+        return {}
+    token = token.strip()
+    if not token:
+        return {}
+    if token.lower().startswith(("bearer ", "token ", "basic ")):
+        return {"Authorization": token}
+    return {"Authorization": "Bearer {}".format(token)}
+
+
+def _api_headers(token=""):
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    headers.update(_github_auth_headers(token))
+    return headers
+
+
+def _api_get(path, token=""):
+    """GET one GitHub REST API path and return the decoded JSON.
+
+    Raises GitHubAPIError instead of silently returning an empty result, so
+    callers can distinguish "no repositories" from "request failed".
+    """
+    try:
+        response = requests.get(
+            GITHUB_API + path, headers=_api_headers(token), timeout=30
+        )
+    except requests.RequestException as exc:
+        raise GitHubAPIError(None, "request failed: {}".format(exc)) from exc
+    if response.status_code != 200:
+        message = "HTTP {}".format(response.status_code)
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+        if isinstance(payload, dict) and payload.get("message"):
+            message = "{} (HTTP {})".format(payload["message"], response.status_code)
+        raise GitHubAPIError(response.status_code, message)
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise GitHubAPIError(
+            response.status_code, "invalid JSON response from GitHub"
+        ) from exc
+
+
+def get_authenticated_login(token=""):
+    """Return the login of the token owner, or None if there is no usable token."""
+    if not _github_auth_headers(token):
+        return None
+    try:
+        account = _api_get("/user", token)
+    except GitHubAPIError:
+        return None
+    if not isinstance(account, dict):
+        return None
+    return account.get("login") or None
+
+
+def get_account_type(username, token=""):
+    """Return ``"Organization"``/``"User"`` for ``username``, or None if unknown."""
+    quoted = quote(username, safe="")
+    try:
+        account = _api_get("/users/{}".format(quoted), token)
+    except GitHubAPIError:
+        account = None
+    if isinstance(account, dict) and account.get("type"):
+        return account["type"]
+    # ``/users/{org}`` is not guaranteed to resolve for organisations, so fall
+    # back to the org endpoint, which unambiguously identifies one.
+    try:
+        org = _api_get("/orgs/{}".format(quoted), token)
+    except GitHubAPIError:
+        org = None
+    if isinstance(org, dict) and org.get("login"):
+        return "Organization"
+    return None
+
+
+def _repos_path(username, page, authenticated_login, account_type):
+    """Build a listing API path that only contains repositories owned by ``username``.
+
+    ``GET /user/repos`` (used by an earlier version whenever a token was
+    supplied) lists every repository the token owner can see, which includes
+    repositories of the organisations the token owner is a member of, and it
+    ignores ``username`` entirely.  Listing must therefore be scoped to the
+    requested account:
+
+    * organisation -> ``/orgs/{org}/repos?type=all``; only repositories owned
+      by that organisation, including private ones the token may access
+    * own user account -> ``/user/repos?affiliation=owner``; keeps private
+      repos, drops organisation/collaborator repos
+    * any other user account -> ``/users/{username}/repos?type=owner``
+    """
+    quoted = quote(username, safe="")
+    if (account_type or "").lower() == "organization":
+        return "/orgs/{}/repos?type=all&per_page={}&page={}".format(
+            quoted, PER_PAGE, page
+        )
+    own_account = bool(authenticated_login) and (
+        authenticated_login.lower() == username.lower()
+    )
+    if own_account:
+        return "/user/repos?affiliation=owner&per_page={}&page={}".format(
+            PER_PAGE, page
+        )
+    return "/users/{}/repos?type=owner&per_page={}&page={}".format(
+        quoted, PER_PAGE, page
+    )
+
+
+def _is_owned_by(repo, username):
+    owner = repo.get("owner") or {}
+    login = owner.get("login") or ""
+    if login:
+        return login.lower() == username.lower()
+    full_name = repo.get("full_name") or ""
+    return full_name.split("/", 1)[0].lower() == username.lower()
+
+
+def _fetch_repos_page(username, page, token="", authenticated_login=None,
+                      account_type=None):
+    """Fetch one raw page of repositories owned by ``username``."""
+    path = _repos_path(username, page, authenticated_login, account_type)
+    repos = _api_get(path, token)
+    if not isinstance(repos, list):
+        return []
+    return [repo for repo in repos if isinstance(repo, dict)]
+
+
+def get_page_of_repos(username, page, token="", authenticated_login=None,
+                      account_type=None):
+    username = username.strip()
+    if account_type is None:
+        account_type = get_account_type(username, token)
+    if authenticated_login is None:
+        authenticated_login = get_authenticated_login(token)
+    repos = _fetch_repos_page(
+        username, page, token, authenticated_login, account_type
+    )
+    return [repo for repo in repos if _is_owned_by(repo, username)]
+
+
+# --- public web fallback -------------------------------------------------
+#
+# api.github.com allows only 60 unauthenticated requests per hour *per IP*.
+# Shared/NATed networks and CI runners exhaust that quickly, which used to make
+# ``dump-github user`` silently return nothing.  github.com's repository pages
+# are not subject to that API quota, so they are used as a read-only fallback
+# for public repositories when no token is configured.
+
+_USER_REPO_TAG_RE = re.compile(r'<a\b[^>]*itemprop="name codeRepository"[^>]*>')
+_WEB_REPO_HREF_RE = re.compile(r'href="/([^"/]+)/([^"/?#]+)"')
+_WEB_NEXT_RE = re.compile(r'rel="next"')
+_WEB_NON_REPO_PATHS = {
+    "followers",
+    "following",
+    "people",
+    "packages",
+    "projects",
+    "repositories",
+    "settings",
+    "sponsoring",
+}
+
+
+def _web_get(url):
+    try:
+        response = requests.get(
+            url, headers={"User-Agent": WEB_USER_AGENT}, timeout=30
+        )
+    except requests.RequestException as exc:
+        raise GitHubAPIError(None, "web request failed: {}".format(exc)) from exc
+    if response.status_code != 200:
+        raise GitHubAPIError(
+            response.status_code,
+            "github.com returned HTTP {}".format(response.status_code),
+        )
+    return response.text
+
+
+def _web_repo(owner, name):
+    return {
+        "name": name,
+        "full_name": "{}/{}".format(owner, name),
+        "owner": {"login": owner},
+        "clone_url": "{}/{}/{}.git".format(GITHUB_WEB, owner, name),
+        # The default branch is not exposed by the web listing; zip downloads
+        # then use the HEAD archive instead.
+    }
+
+
+def _parse_user_repos_page(html, username):
+    repos = []
+    seen = set()
+    for tag in _USER_REPO_TAG_RE.findall(html):
+        match = _WEB_REPO_HREF_RE.search(tag)
+        if not match:
+            continue
+        owner, name = match.group(1), match.group(2)
+        if owner.lower() != username.lower() or name in seen:
+            continue
+        seen.add(name)
+        repos.append(_web_repo(owner, name))
+    return repos
+
+
+def _parse_org_repos_page(html, org):
+    repos = []
+    seen = set()
+    for owner, name in _WEB_REPO_HREF_RE.findall(html):
+        if owner.lower() != org.lower():
+            continue
+        if name.lower() in _WEB_NON_REPO_PATHS or name in seen:
+            continue
+        seen.add(name)
+        repos.append(_web_repo(owner, name))
+    return repos
+
+
+def _web_page_url(username, page, is_org):
+    quoted = quote(username, safe="")
+    if is_org:
+        return "{}/orgs/{}/repositories?page={}".format(GITHUB_WEB, quoted, page)
+    return "{}/{}?tab=repositories&page={}".format(GITHUB_WEB, quoted, page)
+
+
+def _parse_web_page(html, username, is_org):
+    if is_org:
+        return _parse_org_repos_page(html, username)
+    return _parse_user_repos_page(html, username)
+
+
+def _search_via_web(username, account_type):
+    """List public repositories from github.com when the REST API is unavailable."""
+    is_org = (account_type or "").lower() == "organization"
+    first = _web_get(_web_page_url(username, 1, is_org))
+    repos = _parse_web_page(first, username, is_org)
+    if not repos and account_type is None:
+        # The account may be an organisation: its profile page redirects to
+        # github.com/{org} and does not contain the plain repository list.
+        try:
+            org_first = _web_get(_web_page_url(username, 1, True))
+        except GitHubAPIError as exc:
+            if exc.status_code == 404:
+                return []
+            raise
+        org_repos = _parse_org_repos_page(org_first, username)
+        if not org_repos:
+            return []
+        is_org = True
+        repos = org_repos
+        first = org_first
+    if not repos:
+        return []
+    page = 1
+    while _WEB_NEXT_RE.search(first):
+        page += 1
+        html = _web_get(_web_page_url(username, page, is_org))
+        page_repos = _parse_web_page(html, username, is_org)
+        if not page_repos:
+            break
+        repos.extend(page_repos)
+        first = html
+    return repos
+
+
+def _search_via_api(username, token, authenticated_login, account_type):
+    page = 0
+    res_repos = []
+    while True:
+        page += 1
+        repos = _fetch_repos_page(
+            username, page, token, authenticated_login, account_type
+        )
+        if len(repos) == 0:
+            break
+        res_repos += repos
+        if len(repos) < PER_PAGE:
+            break
+    return res_repos
+
+
+def search_user_repos(username, token=""):
+    username = username.strip()
+    authenticated_login = get_authenticated_login(token)
+    account_type = get_account_type(username, token)
+    try:
+        repos = _search_via_api(
+            username, token, authenticated_login, account_type
+        )
+    except GitHubAPIError as exc:
+        if token or exc.status_code == 404:
+            raise
+        warnings.warn(
+            "GitHub API request failed ({}); falling back to the public GitHub "
+            "web listing. Only public repositories can be listed without a "
+            "token.".format(exc),
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        repos = _search_via_web(username, account_type)
+
+    # Never return repositories that belong to somebody else (e.g. a user repo
+    # returned for an organisation, or an organisation the token owner is in).
+    result = []
+    seen = set()
+    for repo in repos:
+        if not _is_owned_by(repo, username):
+            continue
+        key = (repo.get("full_name") or repo.get("name") or "").lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(repo)
+    return result
+
+
+# Backward-compatible alias for the historical typo
+serach_user_repos = search_user_repos

dump_github/main.py

@@ -1,109 +1,152 @@
-import argparse
-import os
-import subprocess
-from urllib.parse import quote
-
-from .lib import search_user_repos
-
-parser = argparse.ArgumentParser(
-    prog="dump-github",
-    description="Backup users github repo.",
-    epilog="https://github.com/Core2002/dump_github",
-)
-
-parser.add_argument("username")
-parser.add_argument(
-    "-d", "--download_zip", action="store_true", help="only download zip file"
-)
-parser.add_argument("-p", "--print", action="store_true", help="only print urls")
-parser.add_argument(
-    "--token",
-    action="store",
-    default="",
-    help="GitHub personal access token (or set GITHUB_TOKEN). Required for private repos and higher API rate limits.",
-)
-parser.add_argument(
-    "--limit_size",
-    type=int,
-    default=100,
-    help="limit size(MB) of download zip file, if 0 then no limit(default:100).",
-)
-
-args = parser.parse_args()
-
-
-def clone_repo(repo, token=""):
-    name = repo["name"]
-    url = repo["clone_url"]
-    if token:
-        url = url.replace(
-            "https://",
-            "https://x-access-token:{}@".format(quote(token, safe="")),
-            1,
-        )
-    print("Clone repo: {}".format(name))
-    subprocess.run(["git", "clone", url], check=False)
-
-
-def download_zip(user_name, reop, token=""):
-    ref = reop.get("default_branch") or "main"
-    max_size = args.limit_size * 1000 * 1000
-    file_name = "./{}_{}.zip".format(user_name, reop["name"])
-    curl_cmd = [
-        "curl",
-        "-sS",
-        "-L",
-        "--connect-timeout",
-        "5",
-        "--retry",
-        "3",
-        "--retry-delay",
-        "3",
-    ]
-    if max_size > 0:
-        curl_cmd.extend(["--max-filesize", str(max_size)])
-    if token:
-        url = "https://api.github.com/repos/{}/{}/zipball/{}".format(
-            user_name, reop["name"], ref
-        )
-        curl_cmd.extend(
-            [
-                "-H",
-                "Authorization: Bearer {}".format(token),
-                "-H",
-                "Accept: application/vnd.github+json",
-                "-o",
-                file_name,
-                url,
-            ]
-        )
-    else:
-        url = "https://github.com/{}/{}/archive/refs/heads/{}.zip".format(
-            user_name, reop["name"], ref
-        )
-        curl_cmd.extend(["-o", file_name, url])
-    print("Download {} : {}".format(reop["name"], url))
-    subprocess.run(curl_cmd, check=False)
-    if (
-        max_size > 0
-        and os.path.exists(file_name)
-        and os.stat(file_name).st_size > max_size
-    ):
-        os.remove(file_name)
-        print("Removed {} because it exceeds the limit size.".format(file_name))
-
-
-def main():
-    token = (args.token or "").strip() or (os.environ.get("GITHUB_TOKEN") or "").strip()
-    repos = search_user_repos(args.username, token)
-    for repo in repos:
-        if args.print == True:
-            print(repo["clone_url"])
-        elif args.download_zip == True:
-            download_zip(args.username, repo, token)
-        else:
-            clone_repo(repo, token)
-
-
-if __name__ == "__main__":
-    main()
+import argparse
+import os
+import subprocess
+import sys
+
+from ._version import __version__
+from .lib import GitHubAPIError, search_user_repos
+
+# One-shot credential helper: git asks for credentials, the helper answers with
+# the token from the environment.  The token is therefore never part of the
+# clone URL and never gets written to the cloned repository's .git/config.
+GIT_CREDENTIAL_HELPER = (
+    '!f() { test "$1" = get || return 0; '
+    'echo username=x-access-token; '
+    'echo "password=$DUMP_GITHUB_TOKEN"; }; f'
+)
+
+parser = argparse.ArgumentParser(
+    prog="dump-github",
+    description="Backup users github repo.",
+    epilog="https://github.com/Core2002/dump_github",
+)
+
+parser.add_argument("username")
+parser.add_argument(
+    "-d", "--download_zip", action="store_true", help="only download zip file"
+)
+parser.add_argument("-p", "--print", action="store_true", help="only print urls")
+parser.add_argument(
+    "--version", action="version", version="%(prog)s {}".format(__version__)
+)
+parser.add_argument(
+    "--token",
+    action="store",
+    default="",
+    help="GitHub personal access token (or set GITHUB_TOKEN). Required for private repos and higher API rate limits.",
+)
+parser.add_argument(
+    "--limit_size",
+    type=int,
+    default=100,
+    help="limit size(MB) of download zip file, if 0 then no limit(default:100).",
+)
+
+
+def clone_repo(repo, token=""):
+    name = repo["name"]
+    url = repo["clone_url"]
+    cmd = ["git", "clone", url]
+    env = None
+    if token:
+        # Use a credential helper instead of https://x-access-token:TOKEN@...
+        # so the token does not leak into `ps` output or .git/config.
+        cmd = [
+            "git",
+            "-c",
+            "credential.helper=",
+            "-c",
+            "credential.helper={}".format(GIT_CREDENTIAL_HELPER),
+            "clone",
+            url,
+        ]
+        env = os.environ.copy()
+        env["DUMP_GITHUB_TOKEN"] = token
+        env["GIT_TERMINAL_PROMPT"] = "0"
+    print("Clone repo: {}".format(name))
+    subprocess.run(cmd, env=env, check=False)
+
+
+def download_zip(user_name, reop, token="", limit_size=100):
+    ref = reop.get("default_branch")
+    # Always archive the repository the API actually listed.  Using the
+    # positional username here would point at the wrong owner whenever the
+    # repo does not belong to that user.
+    full_name = reop.get("full_name") or "{}/{}".format(user_name, reop["name"])
+    max_size = limit_size * 1000 * 1000
+    file_name = "./{}.zip".format(full_name.replace("/", "_"))
+    curl_cmd = [
+        "curl",
+        "-sS",
+        "-L",
+        "--connect-timeout",
+        "5",
+        "--retry",
+        "3",
+        "--retry-delay",
+        "3",
+    ]
+    if max_size > 0:
+        curl_cmd.extend(["--max-filesize", str(max_size)])
+    if token:
+        url = "https://api.github.com/repos/{}/zipball".format(full_name)
+        if ref:
+            url += "/{}".format(ref)
+        curl_cmd.extend(
+            [
+                "-H",
+                "Authorization: Bearer {}".format(token),
+                "-H",
+                "Accept: application/vnd.github+json",
+                "-o",
+                file_name,
+                url,
+            ]
+        )
+    else:
+        # The web listing does not know the default branch; GitHub resolves
+        # HEAD to it.
+        if ref:
+            url = "https://github.com/{}/archive/refs/heads/{}.zip".format(full_name, ref)
+        else:
+            url = "https://github.com/{}/archive/HEAD.zip".format(full_name)
+        curl_cmd.extend(["-o", file_name, url])
+    print("Download {} : {}".format(reop["name"], url))
+    subprocess.run(curl_cmd, check=False)
+    if (
+        max_size > 0
+        and os.path.exists(file_name)
+        and os.stat(file_name).st_size > max_size
+    ):
+        os.remove(file_name)
+        print("Removed {} because it exceeds the limit size.".format(file_name))
+
+
+def main(argv=None):
+    args = parser.parse_args(argv)
+    token = (args.token or "").strip() or (os.environ.get("GITHUB_TOKEN") or "").strip()
+    try:
+        repos = search_user_repos(args.username, token)
+    except GitHubAPIError as exc:
+        print(
+            "error: cannot list repositories for {}: {}".format(args.username, exc),
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+    if not repos:
+        print(
+            "No public repositories found for {}.".format(args.username),
+            file=sys.stderr,
+        )
+        return
+    for repo in repos:
+        if args.print:
+            print(repo["clone_url"])
+        elif args.download_zip:
+            download_zip(args.username, repo, token, args.limit_size)
+        else:
+            clone_repo(repo, token)
+
+
+if __name__ == "__main__":
+    main()

dump_github-0.2.1.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: dump-github
+Version: 0.2.1
+Summary: Back up users' GitHub repositories in case they need them later.
+Author-email: core2002 <core2002@aliyun.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Core2002/dump_github
+Project-URL: Repository, https://github.com/Core2002/dump_github
+Project-URL: Issues, https://github.com/Core2002/dump_github/issues
+Project-URL: Changelog, https://github.com/Core2002/dump_github/blob/main/CHANGELOG.md
+Keywords: github,backup,repositories,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: System :: Archiving :: Backup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+### Github Dumper
+
+[![CI](https://github.com/Core2002/dump_github/actions/workflows/ci.yml/badge.svg)](https://github.com/Core2002/dump_github/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dump-github.svg)](https://pypi.org/project/dump-github/)
+
+Github Dumper is a Python program designed to search for users' GitHub repositories and download the repositories. This tool can be used to back up users' GitHub repositories in case they need them later.
+
+**Install (Python 3.10+):**
+
+```
+pip install -U dump-github
+```
+
+**Usage:**
+
+```
+usage: dump-github [-h] [-d] [-p] [--version] [--token TOKEN]
+                   [--limit_size LIMIT_SIZE]
+                   username
+
+Backup users github repo.
+
+positional arguments:
+  username
+
+options:
+  -h, --help            show this help message and exit
+  -d, --download_zip    only download zip file
+  -p, --print           only print urls
+  --version             show program's version number and exit
+  --token TOKEN         GitHub personal access token (or set GITHUB_TOKEN).
+                        Required for private repos and higher API rate limits.
+  --limit_size LIMIT_SIZE
+                        limit size(MB) of download zip file, if 0 then no
+                        limit(default:100).
+
+https://github.com/Core2002/dump_github
+```
+
+### Authentication (token)
+
+GitHub’s API requires a proper `Authorization: Bearer <token>` header. This tool accepts a **personal access token** in two ways (first match wins):
+
+1. **`--token`** on the command line  
+2. **`GITHUB_TOKEN`** environment variable (if `--token` is empty)
+
+**Why use a token?**
+
+- **Private repositories**: Without a token, only public repos are listed and can be cloned or archived. With a token that has the right scopes, you can include private repos you are allowed to access (for example when backing up your own account).
+- **Rate limits**: Authenticated API requests get a much higher limit than anonymous requests.
+
+**Without a token**
+
+Only public repositories can be listed and downloaded. The anonymous GitHub API allows
+60 requests per hour per IP, which shared/NATed networks and CI runners exhaust quickly;
+if `api.github.com` is rate-limited or otherwise unavailable, the tool automatically
+falls back to the public GitHub web listing
+(`github.com/{user}?tab=repositories` / `github.com/orgs/{org}/repositories`), prints a
+warning and keeps going. Private repositories still require a token.
+
+**How the token is used**
+
+- **Listing repos**: sent as `Bearer` on the REST API and scoped strictly to the requested account:
+  - **organisation** → `GET /orgs/{org}/repos?type=all` — only repositories owned by that organisation (private ones included when the token may access them);
+  - **your own user account** → `GET /user/repos?affiliation=owner` — private and public repos, without organisation/collaborator repos;
+  - **any other user** → `GET /users/{username}/repos?type=owner`.
+
+  Repositories whose owner is not the requested account are discarded as a final guard, so a user dump never includes organisation repositories and an organisation dump never includes user repositories.
+- **Clone** (default mode): the token is handed to `git` through a one-shot credential helper (`credential.helper` reads `DUMP_GITHUB_TOKEN` from the child process environment), so the clone URL stays `https://github.com/...`. The token is never shown in `ps` output and never written to the cloned repository's `.git/config`; existing credential helpers are reset for that clone so a stale stored credential cannot shadow the token.
+- **Zip download** (`-d`): uses the [repository archive (zipball)](https://docs.github.com/en/rest/repos/repos#download-a-repository-archive-zip) API with the same `Bearer` header (via `curl`), which works for private repos; without a token, public archive URLs are used instead.
+
+Create a token under GitHub → **Settings** → **Developer settings** → **Personal access tokens**. For private repo backup, enable access to **repository contents** (classic PAT: `repo` scope; fine-grained: read access to the repositories you need).
+
+**Examples**
+
+```bash
+# Public repos only (no token; falls back to the web listing if the API is rate-limited)
+dump-github Core2002 -p
+
+# Public backup without any credentials
+dump-github Core2002 -d
+
+# Token on the command line (private + higher API limits)
+dump-github username --token ghp_xxxxxxxxxxxx
+
+# Back up an organisation (only that organisation's repositories)
+dump-github some-org --token ghp_xxxxxxxxxxxx
+
+# Same, via environment variable (recommended to avoid shell history)
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+dump-github Core2002 -d
+```
+
+**Security note:** Do not commit tokens or paste them into shared logs. Prefer `GITHUB_TOKEN` in a local shell profile or a secret manager, and rotate the token if it leaks. Cloned repositories keep a clean remote URL (`https://github.com/...`), so `.git/config` does not contain the token.
+
+### Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+python -m build                  # dist/: sdist + wheel
+python -m twine check dist/*
+```
+
+CI runs the test suite on Python 3.10, 3.12 and 3.13, and checks the build metadata with `twine check` (`.github/workflows/ci.yml`).
+
+### Releasing
+
+1. Bump `__version__` in `dump_github/_version.py` and move the changelog entries in `CHANGELOG.md` to the new version.
+2. Commit, tag and push:
+   ```bash
+   git tag v0.2.0
+   git push origin main v0.2.0
+   ```
+3. The `Release` workflow runs the tests, builds the sdist and wheel, checks them with `twine check` and publishes both to PyPI through **Trusted Publishing**.
+
+One-time setup on PyPI: add a trusted publisher for the `Core2002/dump_github` repository and the `release.yml` workflow. No PyPI API token is stored in the repository. Manual fallback:
+
+```bash
+python -m build
+python -m twine upload dist/*
+```

dump_github-0.2.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+dump_github/__init__.py,sha256=7bV8yfP0ii_gvNXKfDzFhBj2V5nC82mcJrlZqs9fRZ0,92
+dump_github/_version.py,sha256=HfjVOrpTnmZ-xVFCYSVmX50EXaBQeJteUHG-PD6iQs8,22
+dump_github/lib.py,sha256=elhVYzMSK2abVKPWqQUukQCCNdxdkCjGQPiW7kauGkA,11662
+dump_github/main.py,sha256=unifRRUhyvu_2e7UMmoIxtRbVOANUGUUIQJbhaDQ_I8,4768
+dump_github-0.2.1.dist-info/licenses/LICENSE,sha256=5tQa-lQLqvLhjTuELEk4bm70I5hcdjUeOn4qf3MK84E,1064
+dump_github-0.2.1.dist-info/METADATA,sha256=-Ol1P5UNwJe6OjSiLD6LkFHQKbUO-jHYI5yEV-D7Ru8,7373
+dump_github-0.2.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+dump_github-0.2.1.dist-info/entry_points.txt,sha256=2OAP2WnA1p54LWyCw3tHe44Pf4aR7Thsxf9uWKWfWl8,49
+dump_github-0.2.1.dist-info/top_level.txt,sha256=6oWfdkP2U1AN9zL6AUIUTxe6hYIeo_Nf8M8SWBxElUw,12
+dump_github-0.2.1.dist-info/RECORD,,

{dump_github-0.1.8.dist-info → dump_github-0.2.1.dist-info}/WHEEL

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

{dump_github-0.1.8.dist-info → dump_github-0.2.1.dist-info}/licenses/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Core2002
-
-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
+MIT License
+
+Copyright (c) 2024 Core2002
+
+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.

dump_github-0.1.8.dist-info/METADATA

@@ -1,92 +0,0 @@
-Metadata-Version: 2.4
-Name: dump_github
-Version: 0.1.8
-Summary: This tool can be used to back up users' GitHub repositories in case they need them later.
-Home-page: https://github.com/core2002/dump_github
-Author: core2002
-Author-email: core2002@aliyun.com
-License: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: argparse
-Requires-Dist: requests
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: summary
-
-### Github Dumper
-
-Github Dumper is a Python program designed to search for users' GitHub repositories and download the repositories. This tool can be used to back up users' GitHub repositories in case they need them later.
-
-**Install:**
-
-```
-pip install -U dump-github
-```
-
-**Usage:**
-
-```
-usage: dump-github [-h] [-d] [-p] [--token TOKEN] [--limit_size LIMIT_SIZE] username
-
-Backup users github repo.
-
-positional arguments:
-  username
-
-options:
-  -h, --help            show this help message and exit
-  -d, --download_zip    only download zip file
-  -p, --print           only print urls
-  --token TOKEN         GitHub personal access token (or set GITHUB_TOKEN)
-  --limit_size LIMIT_SIZE
-                        limit size(MB) of download zip file, if 0 then no limit(default:100).
-
-https://github.com/Core2002/dump_github
-```
-
-### Authentication (token)
-
-GitHub’s API requires a proper `Authorization: Bearer <token>` header. This tool accepts a **personal access token** in two ways (first match wins):
-
-1. **`--token`** on the command line  
-2. **`GITHUB_TOKEN`** environment variable (if `--token` is empty)
-
-**Why use a token?**
-
-- **Private repositories**: Without a token, only public repos are listed and can be cloned or archived. With a token that has the right scopes, you can include private repos you are allowed to access (for example when backing up your own account).
-- **Rate limits**: Authenticated API requests get a much higher limit than anonymous requests.
-
-**How the token is used**
-
-- **Listing repos** (`GET /users/{username}/repos`): sent as `Bearer` on the REST API.
-- **Clone** (default mode): HTTPS clone URL is turned into `https://x-access-token:<token>@github.com/...` so `git clone` can access private repos.
-- **Zip download** (`-d`): uses the [repository archive (zipball)](https://docs.github.com/en/rest/repos/repos#download-a-repository-archive-zip) API with the same `Bearer` header (via `curl`), which works for private repos; without a token, public archive URLs are used instead.
-
-Create a token under GitHub → **Settings** → **Developer settings** → **Personal access tokens**. For private repo backup, enable access to **repository contents** (classic PAT: `repo` scope; fine-grained: read access to the repositories you need).
-
-**Examples**
-
-```bash
-# Public repos only (no token)
-dump-github Core2002 -p
-
-# Token on the command line (private + higher API limits)
-dump-github username --token ghp_xxxxxxxxxxxx
-
-# Same, via environment variable (recommended to avoid shell history)
-export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
-dump-github Core2002 -d
-```
-
-**Security note:** Do not commit tokens or paste them into shared logs. Prefer `GITHUB_TOKEN` in a local shell profile or a secret manager, and rotate the token if it leaks.

dump_github-0.1.8.dist-info/RECORD

@@ -1,9 +0,0 @@
-dump_github/__init__.py,sha256=5dzWctgs4c0g7raC2Kzas3wck0zHvXifUnSxy-dCPjg,44
-dump_github/lib.py,sha256=vEpwlJBrRr-g34spJPZmhRC9bdElngaaHCCxCQ86M1A,1843
-dump_github/main.py,sha256=H8QADAbNNbs_zIx5Hk6MzAFLgFfMA7bT06fqRpuyInQ,3150
-dump_github-0.1.8.dist-info/licenses/LICENSE,sha256=ac2hzJN6sGcBrmJXe7CkvzfaYdM5sEo8Ny1BWHML1yk,1084
-dump_github-0.1.8.dist-info/METADATA,sha256=h8x2qKi_OzFpSSunyfHGpSolUrKJGJJZl-YkWDzgfUY,3606
-dump_github-0.1.8.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-dump_github-0.1.8.dist-info/entry_points.txt,sha256=2OAP2WnA1p54LWyCw3tHe44Pf4aR7Thsxf9uWKWfWl8,49
-dump_github-0.1.8.dist-info/top_level.txt,sha256=6oWfdkP2U1AN9zL6AUIUTxe6hYIeo_Nf8M8SWBxElUw,12
-dump_github-0.1.8.dist-info/RECORD,,