dump-github 0.1.7__py3-none-any.whl → 0.2.0__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.0"

dump_github/lib.py

@@ -1,31 +1,158 @@
+from urllib.parse import quote
+
 import requests
 
+GITHUB_API = "https://api.github.com"
+PER_PAGE = 100
+
+
+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, or None on failure."""
+    try:
+        response = requests.get(
+            GITHUB_API + path, headers=_api_headers(token), timeout=30
+        )
+    except requests.RequestException:
+        return None
+    if response.status_code != 200:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+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
+    account = _api_get("/user", token)
+    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="")
+    account = _api_get("/users/{}".format(quoted), token)
+    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.
+    org = _api_get("/orgs/{}".format(quoted), token)
+    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``.
 
-def get_page_of_repos(username, page, token=""):
-    url = "https://api.github.com/users/{}/repos?per_page=200&page={}".format(
-        username, page
+    ``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
     )
-    headers = {"Authorization": token}
-    if token != "":
-        response = requests.get(url, headers=headers)
-    else:
-        response = requests.get(url)
-    if response.status_code == 200:
-        repos = response.json()
-        return repos
-    else:
+
+
+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 serach_user_repos(username, token=""):
+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)]
+
+
+def search_user_repos(username, token=""):
+    username = username.strip()
+    authenticated_login = get_authenticated_login(token)
+    account_type = get_account_type(username, token)
     page = 0
     res_repos = []
 
     while True:
         page += 1
-        repos = get_page_of_repos(username, page, token)
+        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
+
+    # 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).
+    return [repo for repo in res_repos if _is_owned_by(repo, username)]
+
 
-    return res_repos
+# Backward-compatible alias for the historical typo
+serach_user_repos = search_user_repos

dump_github/main.py

@@ -1,6 +1,18 @@
 import argparse
 import os
-from .lib import *
+import subprocess
+
+from ._version import __version__
+from .lib import 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",
@@ -13,7 +25,15 @@ 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 token")
+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,
@@ -21,41 +41,90 @@ parser.add_argument(
     help="limit size(MB) of download zip file, if 0 then no limit(default:100).",
 )
 
-args = parser.parse_args()
-
 
-def clone_repo(repo):
+def clone_repo(repo, token=""):
     name = repo["name"]
     url = repo["clone_url"]
-    size = repo["size"]
+    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))
-    os.system("git clone {}".format(url))
-
-
-def download_zip(user_name, reop):
-    url = f"https://github.com/{user_name}/{reop['name']}/archive/refs/heads/{reop['default_branch']}.zip"
-    max_size = args.limit_size * 1000 * 1000
-    file_name = f"./{user_name}_{reop['name']}.zip"
-    cmd = "curl -L --connect-timeout 5 --retry 3 --retry-delay 3 --max-filesize {} {} -o {}".format(
-        max_size, url, file_name
-    )
-    print(f"Download {reop['name']} : {url}")
-    os.system(cmd)
-    if os.path.exists(file_name) and max_size < os.stat(file_name).st_size:
+    subprocess.run(cmd, env=env, check=False)
+
+
+def download_zip(user_name, reop, token="", limit_size=100):
+    ref = reop.get("default_branch") or "main"
+    # 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, 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(full_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(f"Removed {file_name} because it exceeds the limit size.")
+        print("Removed {} because it exceeds the limit size.".format(file_name))
 
 
-def main():
-    # print(args)
-    repos = serach_user_repos(args.username, args.token)
+def main(argv=None):
+    args = parser.parse_args(argv)
+    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:
+        if args.print:
             print(repo["clone_url"])
-        elif args.download_zip == True:
-            download_zip(args.username, repo)
+        elif args.download_zip:
+            download_zip(args.username, repo, token, args.limit_size)
         else:
-            clone_repo(repo)
+            clone_repo(repo, token)
 
 
 if __name__ == "__main__":

dump_github-0.2.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: dump-github
+Version: 0.2.0
+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.
+
+**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)
+dump-github Core2002 -p
+
+# 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.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dump_github/__init__.py,sha256=7bV8yfP0ii_gvNXKfDzFhBj2V5nC82mcJrlZqs9fRZ0,92
+dump_github/_version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+dump_github/lib.py,sha256=l35zDGPRRKdMv6KzzcqJXnCmOMLrPY07wnsijcwbfCA,5485
+dump_github/main.py,sha256=lYSma1C2m-7Pl5r4zwbEfeZyKqgVf2H2jFwD-98hnYg,4122
+dump_github-0.2.0.dist-info/licenses/LICENSE,sha256=5tQa-lQLqvLhjTuELEk4bm70I5hcdjUeOn4qf3MK84E,1064
+dump_github-0.2.0.dist-info/METADATA,sha256=vjimbmFSa9hnjYn8L58iX79KvNbL3tq104VVsIXg09I,6766
+dump_github-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+dump_github-0.2.0.dist-info/entry_points.txt,sha256=2OAP2WnA1p54LWyCw3tHe44Pf4aR7Thsxf9uWKWfWl8,49
+dump_github-0.2.0.dist-info/top_level.txt,sha256=6oWfdkP2U1AN9zL6AUIUTxe6hYIeo_Nf8M8SWBxElUw,12
+dump_github-0.2.0.dist-info/RECORD,,

{dump_github-0.1.7.dist-info → dump_github-0.2.0.dist-info}/WHEEL

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

dump_github/mylib.py

@@ -1,31 +0,0 @@
-import requests
-
-
-def get_page_of_repos(username, page, token=""):
-    url = "https://api.github.com/users/{}/repos?per_page=200&page={}".format(
-        username, page
-    )
-    headers = {"Authorization": token}
-    if token != "":
-        response = requests.get(url, headers=headers)
-    else:
-        response = requests.get(url)
-    if response.status_code == 200:
-        repos = response.json()
-        return repos
-    else:
-        raise []
-
-
-def serach_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

dump_github-0.1.7.dist-info/METADATA

@@ -1,44 +0,0 @@
-Metadata-Version: 2.1
-Name: dump-github
-Version: 0.1.7
-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
-
-### 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 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
-```

dump_github-0.1.7.dist-info/RECORD

@@ -1,10 +0,0 @@
-dump_github/__init__.py,sha256=3XLRrchVn7g3TYWiQpv3u2lKdTO-jDqg4_0-lpmRuRs,43
-dump_github/lib.py,sha256=hE8ZXBB2BKHlPld0ufUgRaAr2hGouLeQ7jdZuqXX6Q8,716
-dump_github/main.py,sha256=uTPdcVwg0mkmOAGJXpVeBn3m3f7SyNOracyqAnR-KuA,1842
-dump_github/mylib.py,sha256=pHONzAjGbXkmAUvCGn8HkHWS7fyY2qu9R17to6jD1TU,715
-dump_github-0.1.7.dist-info/LICENSE,sha256=5tQa-lQLqvLhjTuELEk4bm70I5hcdjUeOn4qf3MK84E,1064
-dump_github-0.1.7.dist-info/METADATA,sha256=ZwZtZYP6H4p0NrK0La9C7lOeB4frgC2i3lwLPLH2D-Q,1316
-dump_github-0.1.7.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-dump_github-0.1.7.dist-info/entry_points.txt,sha256=2OAP2WnA1p54LWyCw3tHe44Pf4aR7Thsxf9uWKWfWl8,49
-dump_github-0.1.7.dist-info/top_level.txt,sha256=6oWfdkP2U1AN9zL6AUIUTxe6hYIeo_Nf8M8SWBxElUw,12
-dump_github-0.1.7.dist-info/RECORD,,