devpost-api 1.0.1__py3-none-any.whl

devpost_api/__init__.py

@@ -0,0 +1,56 @@
+"""Unofficial Devpost API client with typed models and CLI."""
+
+from ._meta import __version__
+from .client import BatchFailure, DevpostClient, ProjectBatchResult, RetryConfig
+from .exceptions import (
+    DevpostAPIError,
+    GitHubResolutionError,
+    HTTPStatusError,
+    ParseError,
+    RateLimitError,
+)
+from .models import (
+    CreatorProfile,
+    ExternalLink,
+    GitHubRepo,
+    HackathonProjectsPage,
+    HackathonSummary,
+    ProjectDetails,
+    SoftwareSummary,
+    UserSummary,
+)
+from .parsing import (
+    github_owner_repo,
+    hackathon_gallery_url,
+    parse_hackathon_gallery_page,
+    slug_from_project_url,
+    to_hackathon_url,
+    to_project_url,
+)
+
+__all__ = [
+    "DevpostClient",
+    "BatchFailure",
+    "ProjectBatchResult",
+    "RetryConfig",
+    "DevpostAPIError",
+    "HTTPStatusError",
+    "ParseError",
+    "GitHubResolutionError",
+    "RateLimitError",
+    "SoftwareSummary",
+    "UserSummary",
+    "HackathonSummary",
+    "HackathonProjectsPage",
+    "CreatorProfile",
+    "ExternalLink",
+    "GitHubRepo",
+    "ProjectDetails",
+    "to_project_url",
+    "to_hackathon_url",
+    "slug_from_project_url",
+    "github_owner_repo",
+    "hackathon_gallery_url",
+    "parse_hackathon_gallery_page",
+    "__version__",
+]

devpost_api/_meta.py

@@ -0,0 +1,9 @@
+"""Package metadata used across runtime and docs."""
+
+PACKAGE_NAME = "devpost-api"
+__version__ = "1.0.1"
+
+
+def default_user_agent() -> str:
+    """Build the default user-agent from package metadata."""
+    return f"{PACKAGE_NAME}/{__version__}"

devpost_api/cli.py

@@ -0,0 +1,371 @@
+"""CLI for the devpost-api package."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Any
+
+from .client import DevpostClient, RetryConfig
+from .exceptions import DevpostAPIError
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    retry_config = RetryConfig(
+        max_attempts=args.retries,
+        backoff_factor=args.backoff,
+        max_backoff=args.max_backoff,
+        jitter=args.jitter,
+    )
+    client = DevpostClient(
+        timeout=args.timeout,
+        github_token=args.github_token,
+        retry_config=retry_config,
+        max_workers=args.workers,
+        min_request_interval=args.min_interval,
+        cache_ttl=args.cache_ttl,
+    )
+
+    payload: Any
+    partial_failures = False
+    try:
+        if args.command == "software":
+            payload = client.list_software(page=args.page, query=args.query)
+        elif args.command == "users":
+            payload = client.list_users(page=args.page)
+        elif args.command == "hackathons":
+            payload = client.list_hackathons(page=args.page, status=args.status)
+        elif args.command == "project":
+            values = _resolve_many_inputs(
+                single_value=args.slug_or_url,
+                input_file=args.input_file,
+                use_stdin=args.stdin,
+                parser=parser,
+            )
+            if len(values) == 1 and args.input_file is None and not args.stdin:
+                payload = client.get_project(
+                    values[0],
+                    include_github=args.with_github,
+                    raise_on_error=not args.best_effort,
+                )
+            else:
+                report = client.collect_projects(values, include_github=args.with_github)
+                payload = {
+                    "items": report.projects,
+                    "errors": report.failures,
+                    "total_inputs": len(values),
+                }
+                partial_failures = bool(report.failures)
+                if report.failures and not args.best_effort:
+                    raise DevpostAPIError("Batch project fetch failed; use --best-effort to continue on errors.")
+        elif args.command == "hackathon-projects":
+            payload = client.list_hackathon_project_urls(args.hackathon, pages=args.pages)
+        elif args.command == "scout":
+            payload = client.scout_hackathon_projects(
+                args.hackathon,
+                pages=args.pages,
+                include_github=args.with_github,
+                raise_on_error=not args.best_effort,
+            )
+        elif args.command == "github":
+            values = _resolve_many_inputs(
+                single_value=args.repo,
+                input_file=args.input_file,
+                use_stdin=args.stdin,
+                parser=parser,
+            )
+            if len(values) == 1 and args.input_file is None and not args.stdin:
+                payload = client.get_github_repo(values[0])
+            else:
+                items: list[Any] = []
+                errors: list[dict[str, str]] = []
+                for value in values:
+                    try:
+                        items.append(client.get_github_repo(value))
+                    except DevpostAPIError as exc:
+                        if not args.best_effort:
+                            raise
+                        errors.append({"input_value": value, "error": str(exc)})
+                payload = {"items": items, "errors": errors, "total_inputs": len(values)}
+                partial_failures = bool(errors)
+        else:
+            parser.print_help()
+            return 1
+    except DevpostAPIError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    _render_payload(payload, output_format=args.format, fields=args.fields)
+    if partial_failures:
+        return 3
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="devpost-api", description="Unofficial Devpost API wrapper CLI")
+    parser.add_argument("--timeout", type=float, default=15.0, help="HTTP timeout in seconds")
+    parser.add_argument("--github-token", default=None, help="Optional GitHub token for higher rate limits")
+    parser.add_argument(
+        "--format",
+        choices=["json", "jsonl", "csv", "table"],
+        default="json",
+        help="Output format",
+    )
+    parser.add_argument(
+        "--fields",
+        default=None,
+        help="Comma-separated top-level fields to include in output rows",
+    )
+    parser.add_argument("--retries", type=int, default=4, help="Maximum retry attempts for transient failures")
+    parser.add_argument("--backoff", type=float, default=0.5, help="Backoff factor for retries")
+    parser.add_argument("--max-backoff", type=float, default=8.0, help="Maximum retry backoff in seconds")
+    parser.add_argument("--jitter", type=float, default=0.25, help="Retry jitter in seconds")
+    parser.add_argument("--workers", type=int, default=8, help="Parallel workers for bulk operations")
+    parser.add_argument(
+        "--min-interval",
+        type=float,
+        default=0.0,
+        help="Global minimum interval between outbound requests in seconds",
+    )
+    parser.add_argument(
+        "--cache-ttl",
+        type=float,
+        default=0.0,
+        help="In-memory cache TTL for GET requests in seconds",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    software = subparsers.add_parser("software", help="List software entries")
+    software.add_argument("--page", type=int, default=1)
+    software.add_argument("--query", default=None)
+
+    users = subparsers.add_parser("users", help="List users")
+    users.add_argument("--page", type=int, default=1)
+
+    hackathons = subparsers.add_parser("hackathons", help="List hackathons")
+    hackathons.add_argument("--page", type=int, default=1)
+    hackathons.add_argument("--status", default=None, help="Example: open")
+
+    project = subparsers.add_parser("project", help="Fetch project details from a Devpost project page")
+    project.add_argument("slug_or_url", nargs="?", help="Project slug, /software/... path, or full URL")
+    project.add_argument("--with-github", action="store_true", help="Fetch GitHub metadata for linked repos")
+    project.add_argument("--input-file", default=None, help="Path to file with one project URL/slug per line")
+    project.add_argument("--stdin", action="store_true", help="Read project URL/slug values from stdin")
+    project.add_argument(
+        "--best-effort",
+        action="store_true",
+        help="Skip item failures instead of failing the entire command",
+    )
+
+    hackathon_projects = subparsers.add_parser(
+        "hackathon-projects",
+        help="List project URLs from a hackathon project gallery",
+    )
+    hackathon_projects.add_argument(
+        "hackathon",
+        help="Hackathon slug/domain/url, e.g. treehacks-2025 or https://treehacks-2025.devpost.com",
+    )
+    hackathon_projects.add_argument(
+        "--pages",
+        type=_pages_type,
+        default=1,
+        help="Number of gallery pages to scan; use 'all' to scan all pages",
+    )
+
+    scout = subparsers.add_parser(
+        "scout",
+        help="Fetch full project details from a hackathon gallery",
+    )
+    scout.add_argument(
+        "hackathon",
+        help="Hackathon slug/domain/url, e.g. treehacks-2025 or https://treehacks-2025.devpost.com",
+    )
+    scout.add_argument(
+        "--pages",
+        type=_pages_type,
+        default=1,
+        help="Number of gallery pages to scan; use 'all' to scan all pages",
+    )
+    scout.add_argument("--with-github", action="store_true", help="Fetch GitHub metadata for linked repos")
+    scout.add_argument(
+        "--best-effort",
+        action="store_true",
+        help="Skip per-project failures and return only successful items",
+    )
+
+    github = subparsers.add_parser("github", help="Fetch one or more GitHub repositories by URL or owner/repo")
+    github.add_argument("repo", nargs="?")
+    github.add_argument("--input-file", default=None, help="Path to file with one repo value per line")
+    github.add_argument("--stdin", action="store_true", help="Read repo values from stdin")
+    github.add_argument("--best-effort", action="store_true", help="Skip invalid repos in batch mode")
+
+    return parser
+
+
+def _jsonable(value: Any) -> Any:
+    if is_dataclass(value) and not isinstance(value, type):
+        return {k: _jsonable(v) for k, v in asdict(value).items()}
+    if isinstance(value, list):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, dict):
+        return {k: _jsonable(v) for k, v in value.items()}
+    return value
+
+
+def _render_payload(payload: Any, *, output_format: str, fields: str | None) -> None:
+    jsonable = _jsonable(payload)
+    filtered = _apply_fields(jsonable, fields)
+    if output_format == "json":
+        print(json.dumps(filtered, ensure_ascii=False, indent=2))
+        return
+    if output_format == "jsonl":
+        for item in _to_output_rows(filtered):
+            print(json.dumps(item, ensure_ascii=False))
+        return
+    if output_format == "csv":
+        _print_csv(filtered)
+        return
+    _print_table(filtered)
+
+
+def _apply_fields(value: Any, fields: str | None) -> Any:
+    selected = _parse_fields(fields)
+    if not selected:
+        return value
+    if isinstance(value, list):
+        return [_select_fields_from_row(item, selected) for item in value]
+    if isinstance(value, dict):
+        if "items" in value and isinstance(value["items"], list):
+            copied = dict(value)
+            copied["items"] = [_select_fields_from_row(item, selected) for item in value["items"]]
+            return copied
+        return _select_fields_from_row(value, selected)
+    return value
+
+
+def _select_fields_from_row(value: Any, selected: list[str]) -> Any:
+    if not isinstance(value, dict):
+        return value
+    return {key: value.get(key) for key in selected if key in value}
+
+
+def _to_output_rows(value: Any) -> list[Any]:
+    if isinstance(value, list):
+        return value
+    if isinstance(value, dict) and "items" in value and isinstance(value["items"], list):
+        return value["items"]
+    return [value]
+
+
+def _print_csv(value: Any) -> None:
+    rows = _normalize_tabular_rows(_to_output_rows(value))
+    if not rows:
+        return
+    fieldnames = _discover_fieldnames(rows)
+    writer = csv.DictWriter(sys.stdout, fieldnames=fieldnames, lineterminator="\n")
+    writer.writeheader()
+    for row in rows:
+        writer.writerow({field: _stringify_cell(row.get(field)) for field in fieldnames})
+
+
+def _print_table(value: Any) -> None:
+    rows = _normalize_tabular_rows(_to_output_rows(value))
+    if not rows:
+        return
+    columns = _discover_fieldnames(rows)
+    matrix: list[list[str]] = [[_stringify_cell(row.get(column)) for column in columns] for row in rows]
+    widths = [len(column) for column in columns]
+    for row in matrix:
+        for idx, cell in enumerate(row):
+            widths[idx] = max(widths[idx], len(cell))
+    header = " | ".join(columns[idx].ljust(widths[idx]) for idx in range(len(columns)))
+    separator = "-+-".join("-" * widths[idx] for idx in range(len(columns)))
+    print(header)
+    print(separator)
+    for row in matrix:
+        print(" | ".join(row[idx].ljust(widths[idx]) for idx in range(len(columns))))
+
+
+def _normalize_tabular_rows(rows: list[Any]) -> list[dict[str, Any]]:
+    normalized: list[dict[str, Any]] = []
+    for row in rows:
+        if isinstance(row, dict):
+            normalized.append(row)
+        else:
+            normalized.append({"value": row})
+    return normalized
+
+
+def _discover_fieldnames(rows: list[dict[str, Any]]) -> list[str]:
+    fieldnames: list[str] = []
+    for row in rows:
+        for key in row:
+            if key not in fieldnames:
+                fieldnames.append(key)
+    return fieldnames
+
+
+def _stringify_cell(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, (str, int, float, bool)):
+        return str(value)
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _resolve_many_inputs(
+    *,
+    single_value: str | None,
+    input_file: str | None,
+    use_stdin: bool,
+    parser: argparse.ArgumentParser,
+) -> list[str]:
+    values: list[str] = []
+    if single_value:
+        values.append(single_value)
+    if input_file:
+        try:
+            text = Path(input_file).read_text(encoding="utf-8")
+        except OSError as exc:
+            parser.error(f"Cannot read --input-file {input_file}: {exc}")
+        values.extend(_split_lines(text))
+    if use_stdin:
+        values.extend(_split_lines(sys.stdin.read()))
+    if not values:
+        parser.error("Provide a positional value, --input-file, or --stdin.")
+    return values
+
+
+def _split_lines(text: str) -> list[str]:
+    values: list[str] = []
+    for raw_line in text.splitlines():
+        value = raw_line.strip()
+        if value and not value.startswith("#"):
+            values.append(value)
+    return values
+
+
+def _parse_fields(fields: str | None) -> list[str]:
+    if fields is None:
+        return []
+    return [item.strip() for item in fields.split(",") if item.strip()]
+
+
+def _pages_type(value: str) -> int | None:
+    if value.lower() == "all":
+        return None
+    num = int(value)
+    if num < 1:
+        raise argparse.ArgumentTypeError("pages must be >= 1 or 'all'")
+    return num
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())