devpost-api 1.0.1__py3-none-any.whl

devpost_api/models.py

@@ -0,0 +1,203 @@
+"""Typed models used by the Devpost API wrapper."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class SoftwareSummary:
+    id: int
+    name: str
+    slug: str
+    url: str
+    tagline: str | None = None
+    description: str | None = None
+    publicly_visible: bool | None = None
+    thumbnail: str | None = None
+
+    @classmethod
+    def from_json(cls, payload: dict[str, Any]) -> SoftwareSummary:
+        return cls(
+            id=int(payload.get("id", 0)),
+            name=str(payload.get("name", "")),
+            slug=str(payload.get("slug", "")),
+            url=str(payload.get("url", "")),
+            tagline=_maybe_str(payload.get("tagline")),
+            description=_maybe_str(payload.get("description")),
+            publicly_visible=_maybe_bool(payload.get("publicly_visible")),
+            thumbnail=_maybe_str(payload.get("thumbnail")),
+        )
+
+
+@dataclass
+class UserSummary:
+    screen_name: str
+    full_name: str | None = None
+    photo: str | None = None
+
+    @classmethod
+    def from_json(cls, payload: dict[str, Any]) -> UserSummary:
+        return cls(
+            screen_name=str(payload.get("screen_name", "")),
+            full_name=_maybe_str(payload.get("full_name")),
+            photo=_maybe_str(payload.get("photo")),
+        )
+
+
+@dataclass
+class HackathonSummary:
+    id: int
+    title: str
+    open_state: str | None = None
+    url: str | None = None
+    location: str | None = None
+    thumbnail_url: str | None = None
+    submission_period_dates: str | None = None
+    registrations_count: int | None = None
+    prize_amount: str | None = None
+    themes: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, payload: dict[str, Any]) -> HackathonSummary:
+        location_payload = payload.get("displayed_location")
+        location = None
+        if isinstance(location_payload, dict):
+            value = location_payload.get("location")
+            if isinstance(value, str):
+                location = value
+
+        return cls(
+            id=int(payload.get("id", 0)),
+            title=str(payload.get("title", "")),
+            open_state=_maybe_str(payload.get("open_state")),
+            url=_maybe_str(payload.get("url")),
+            location=location,
+            thumbnail_url=_maybe_str(payload.get("thumbnail_url")),
+            submission_period_dates=_maybe_str(payload.get("submission_period_dates")),
+            registrations_count=_maybe_int(payload.get("registrations_count")),
+            prize_amount=_maybe_str(payload.get("prize_amount")),
+            themes=_parse_theme_names(payload.get("themes")),
+        )
+
+
+@dataclass
+class HackathonProjectsPage:
+    hackathon_url: str
+    page: int
+    total_pages: int
+    project_urls: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ExternalLink:
+    url: str
+    label: str | None = None
+    domain: str | None = None
+    is_github: bool = False
+
+
+@dataclass
+class CreatorProfile:
+    name: str
+    profile_url: str | None = None
+    photo: str | None = None
+
+
+@dataclass
+class GitHubRepo:
+    owner: str
+    name: str
+    full_name: str
+    html_url: str
+    description: str | None = None
+    stargazers_count: int | None = None
+    forks_count: int | None = None
+    open_issues_count: int | None = None
+    language: str | None = None
+    license_name: str | None = None
+    default_branch: str | None = None
+    updated_at: str | None = None
+
+    @classmethod
+    def from_json(cls, payload: dict[str, Any]) -> GitHubRepo:
+        owner_name = ""
+        owner_payload = payload.get("owner")
+        if isinstance(owner_payload, dict):
+            login = owner_payload.get("login")
+            if isinstance(login, str):
+                owner_name = login
+        full_name = str(payload.get("full_name", ""))
+        repo_name = str(payload.get("name", ""))
+        if not owner_name and "/" in full_name:
+            owner_name = full_name.split("/", 1)[0]
+        license_name = None
+        license_payload = payload.get("license")
+        if isinstance(license_payload, dict):
+            license_value = license_payload.get("name")
+            if isinstance(license_value, str):
+                license_name = license_value
+
+        return cls(
+            owner=owner_name,
+            name=repo_name,
+            full_name=full_name,
+            html_url=str(payload.get("html_url", "")),
+            description=_maybe_str(payload.get("description")),
+            stargazers_count=_maybe_int(payload.get("stargazers_count")),
+            forks_count=_maybe_int(payload.get("forks_count")),
+            open_issues_count=_maybe_int(payload.get("open_issues_count")),
+            language=_maybe_str(payload.get("language")),
+            license_name=license_name,
+            default_branch=_maybe_str(payload.get("default_branch")),
+            updated_at=_maybe_str(payload.get("updated_at")),
+        )
+
+
+@dataclass
+class ProjectDetails:
+    source_url: str
+    slug: str
+    name: str
+    software_id: int | None = None
+    tagline: str | None = None
+    description: str | None = None
+    hero_image: str | None = None
+    image_urls: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+    submitted_to: list[str] = field(default_factory=list)
+    creators: list[str] = field(default_factory=list)
+    creator_profiles: list[CreatorProfile] = field(default_factory=list)
+    links: list[ExternalLink] = field(default_factory=list)
+    github_urls: list[str] = field(default_factory=list)
+    github_repos: list[GitHubRepo] = field(default_factory=list)
+
+
+def _maybe_str(value: Any) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _maybe_bool(value: Any) -> bool | None:
+    return value if isinstance(value, bool) else None
+
+
+def _maybe_int(value: Any) -> int | None:
+    try:
+        return int(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _parse_theme_names(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+
+    names: list[str] = []
+    for item in value:
+        if not isinstance(item, dict):
+            continue
+        name = item.get("name")
+        if isinstance(name, str) and name and name not in names:
+            names.append(name)
+    return names

devpost_api/parsing.py

@@ -0,0 +1,404 @@
+"""HTML and URL parsing helpers."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from html.parser import HTMLParser
+from urllib.parse import ParseResult, urljoin, urlparse, urlunparse
+
+from .exceptions import GitHubResolutionError
+from .models import CreatorProfile, ExternalLink, HackathonProjectsPage, ProjectDetails
+
+DEVPOST_PROJECT_PREFIX = "https://devpost.com/software/"
+DEVPOST_DOMAIN = "devpost.com"
+_GITHUB_HREF_RE = re.compile(
+    r"""href=["'](https?://github\.com/[^/\s"'<>]+/[^"\s'<>]+)["']"""
+)
+_SOFTWARE_ID_RE = re.compile(r"software_id=(\d+)")
+_HREF_RE = re.compile(r"""href=["']([^"'<>]+)["']""")
+_GALLERY_PAGE_RE = re.compile(r"project-gallery\?page=(\d+)")
+
+
+def to_project_url(slug_or_url: str) -> str:
+    """Normalize a project slug/path/url to an absolute Devpost project URL."""
+    value = slug_or_url.strip()
+    if not value:
+        raise ValueError("slug_or_url cannot be empty")
+
+    parsed = urlparse(value)
+    if parsed.scheme in {"http", "https"} and parsed.netloc:
+        return value
+
+    cleaned = value.strip("/")
+    if cleaned.startswith("software/"):
+        cleaned = cleaned.split("/", 1)[1]
+    return f"{DEVPOST_PROJECT_PREFIX}{cleaned}"
+
+
+def to_hackathon_url(slug_or_url: str) -> str:
+    """Normalize a hackathon slug/domain/url to an absolute hackathon base URL."""
+    value = slug_or_url.strip().strip("/")
+    if not value:
+        raise ValueError("slug_or_url cannot be empty")
+
+    parsed = urlparse(value)
+    if parsed.scheme in {"http", "https"} and parsed.netloc:
+        return f"{parsed.scheme}://{parsed.netloc}"
+
+    if value.endswith(f".{DEVPOST_DOMAIN}"):
+        return f"https://{value}"
+
+    if "." not in value:
+        return f"https://{value}.{DEVPOST_DOMAIN}"
+
+    return f"https://{value}"
+
+
+def hackathon_gallery_url(hackathon_slug_or_url: str, page: int = 1) -> str:
+    base = to_hackathon_url(hackathon_slug_or_url).rstrip("/")
+    if page <= 1:
+        return f"{base}/project-gallery"
+    return f"{base}/project-gallery?page={page}"
+
+
+def parse_hackathon_gallery_page(hackathon_url: str, page: int, html: str) -> HackathonProjectsPage:
+    project_urls = _extract_project_urls_from_gallery_html(html)
+    page_nums = [int(match.group(1)) for match in _GALLERY_PAGE_RE.finditer(html)]
+    total_pages = max(page_nums) if page_nums else max(1, page)
+    return HackathonProjectsPage(
+        hackathon_url=to_hackathon_url(hackathon_url),
+        page=page,
+        total_pages=total_pages,
+        project_urls=project_urls,
+    )
+
+
+def slug_from_project_url(url: str) -> str:
+    parsed = urlparse(url)
+    path = parsed.path.strip("/")
+    if path.startswith("software/"):
+        return path.split("/", 1)[1]
+    return path
+
+
+def github_owner_repo(url_or_owner_repo: str) -> tuple[str, str]:
+    """Return (owner, repo) from a GitHub URL or owner/repo string."""
+    value = url_or_owner_repo.strip()
+    if not value:
+        raise GitHubResolutionError("Empty GitHub identifier")
+
+    if value.count("/") == 1 and "://" not in value:
+        owner, repo = value.split("/", 1)
+        repo = repo[:-4] if repo.endswith(".git") else repo
+        if owner and repo:
+            return owner, repo
+
+    parsed = urlparse(value)
+    if parsed.netloc and parsed.netloc.lower().endswith("github.com"):
+        parts = [p for p in parsed.path.split("/") if p]
+        if len(parts) >= 2:
+            owner = parts[0]
+            repo = parts[1]
+            repo = repo[:-4] if repo.endswith(".git") else repo
+            if owner and repo:
+                return owner, repo
+    raise GitHubResolutionError(f"Cannot resolve GitHub owner/repo from: {value}")
+
+
+def parse_project_details(url: str, html: str) -> ProjectDetails:
+    parser = _ProjectParser(url)
+    parser.feed(html)
+    parser.close()
+
+    software_id: int | None = None
+    id_match = _SOFTWARE_ID_RE.search(html)
+    if id_match:
+        software_id = int(id_match.group(1))
+
+    github_urls = list(_unique(parser.github_urls + _extract_github_urls(html)))
+
+    return ProjectDetails(
+        source_url=url,
+        slug=slug_from_project_url(url),
+        name=parser.name or parser.og_title or "",
+        software_id=software_id,
+        tagline=parser.tagline,
+        description=parser.description,
+        hero_image=parser.hero_image,
+        image_urls=parser.image_urls,
+        tags=parser.tags,
+        submitted_to=parser.submitted_to,
+        creators=parser.creators,
+        creator_profiles=parser.creator_profiles,
+        links=parser.links,
+        github_urls=github_urls,
+    )
+
+
+def _extract_github_urls(html: str) -> list[str]:
+    return list(_unique(match.group(1).rstrip(").,;") for match in _GITHUB_HREF_RE.finditer(html)))
+
+
+def _extract_project_urls_from_gallery_html(html: str) -> list[str]:
+    project_urls: list[str] = []
+    for match in _HREF_RE.finditer(html):
+        href = match.group(1).strip().rstrip(").,;")
+        if not href:
+            continue
+        normalized = _normalize_devpost_software_href(href)
+        if normalized:
+            project_urls.append(normalized)
+    return _unique(project_urls)
+
+
+def _normalize_devpost_software_href(href: str) -> str | None:
+    if href.startswith("//"):
+        candidate = f"https:{href}"
+    elif href.startswith("/"):
+        candidate = urljoin("https://devpost.com", href)
+    elif href.startswith("http://") or href.startswith("https://"):
+        candidate = href
+    else:
+        return None
+
+    parsed = urlparse(candidate)
+    netloc = parsed.netloc.lower().replace("www.", "")
+    if netloc != DEVPOST_DOMAIN:
+        return None
+    if not parsed.path.startswith("/software/"):
+        return None
+    slug = parsed.path.removeprefix("/software/").strip("/")
+    if not slug:
+        return None
+    clean_path = f"/software/{slug.split('/', 1)[0]}"
+    return urlunparse(("https", DEVPOST_DOMAIN, clean_path, "", "", ""))
+
+
+def _unique(values: Iterable[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for value in values:
+        if value in seen:
+            continue
+        seen.add(value)
+        out.append(value)
+    return out
+
+
+class _ProjectParser(HTMLParser):
+    def __init__(self, source_url: str) -> None:
+        super().__init__(convert_charrefs=True)
+        self.source_url = source_url
+        self.name = ""
+        self.tagline: str | None = None
+        self.description: str | None = None
+        self.og_title = ""
+        self.hero_image: str | None = None
+        self.image_urls: list[str] = []
+        self.tags: list[str] = []
+        self.submitted_to: list[str] = []
+        self.creators: list[str] = []
+        self.creator_profiles: list[CreatorProfile] = []
+        self.links: list[ExternalLink] = []
+        self.github_urls: list[str] = []
+
+        self._in_h1 = False
+        self._in_h3 = False
+        self._active_link: dict[str, str] | None = None
+        self._active_submission_link = False
+        self._active_creator_profile: dict[str, str] | None = None
+        self._active_tag_text: str | None = None
+
+        self._links_depth = 0
+        self._built_with_depth = 0
+        self._submissions_depth = 0
+        self._team_depth = 0
+
+    def handle_starttag(self, tag: str, attrs_list: list[tuple[str, str | None]]) -> None:
+        attrs = {k: (v or "") for k, v in attrs_list}
+
+        if self._links_depth:
+            self._links_depth += 1
+        if self._built_with_depth:
+            self._built_with_depth += 1
+        if self._submissions_depth:
+            self._submissions_depth += 1
+        if self._team_depth:
+            self._team_depth += 1
+
+        if tag == "meta":
+            self._parse_meta(attrs)
+            return
+
+        if tag == "h1" and not self.name:
+            self._in_h1 = True
+        if tag == "h3" and self.tagline is None:
+            self._in_h3 = True
+
+        class_value = attrs.get("class", "")
+        element_id = attrs.get("id", "")
+
+        if tag == "img":
+            raw_src = attrs.get("src") or attrs.get("data-src")
+            if raw_src:
+                image_url = self._normalize_url(raw_src)
+                if image_url:
+                    self._add_image(image_url)
+                    if self._active_creator_profile is not None:
+                        self._active_creator_profile["photo"] = image_url
+
+        if tag == "nav" and "app-links" in class_value:
+            self._links_depth = 1
+        if element_id == "built-with":
+            self._built_with_depth = 1
+        if element_id == "submissions":
+            self._submissions_depth = 1
+        if element_id == "app-team":
+            self._team_depth = 1
+
+        href = attrs.get("href")
+        if tag == "a" and href:
+            if self._links_depth:
+                self._active_link = {"href": href, "text": ""}
+            if self._submissions_depth:
+                self._active_submission_link = True
+            if self._team_depth and "user-profile-link" in class_value:
+                self._active_creator_profile = {"href": href, "name": ""}
+            if self._built_with_depth:
+                self._active_tag_text = ""
+        elif tag == "span" and self._built_with_depth and "cp-tag" in class_value:
+            self._active_tag_text = ""
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "h1":
+            self._in_h1 = False
+        if tag == "h3":
+            self._in_h3 = False
+        if tag == "a":
+            self._finalize_link()
+            self._finalize_creator_profile()
+            self._active_submission_link = False
+            self._finalize_tag()
+        if tag == "span":
+            self._finalize_tag()
+
+        if self._links_depth:
+            self._links_depth -= 1
+        if self._built_with_depth:
+            self._built_with_depth -= 1
+        if self._submissions_depth:
+            self._submissions_depth -= 1
+        if self._team_depth:
+            self._team_depth -= 1
+
+    def handle_data(self, data: str) -> None:
+        text = " ".join(data.split())
+        if not text:
+            return
+
+        if self._in_h1 and not self.name:
+            self.name = text
+        elif self._in_h3 and self.tagline is None:
+            self.tagline = text
+
+        if self._active_link is not None:
+            current = self._active_link.get("text", "")
+            self._active_link["text"] = f"{current} {text}".strip()
+
+        if self._active_submission_link:
+            if text not in self.submitted_to:
+                self.submitted_to.append(text)
+
+        if self._active_creator_profile is not None:
+            current = self._active_creator_profile.get("name", "")
+            self._active_creator_profile["name"] = f"{current} {text}".strip()
+
+        if self._active_tag_text is not None:
+            self._active_tag_text = f"{self._active_tag_text} {text}".strip()
+
+    def _parse_meta(self, attrs: dict[str, str]) -> None:
+        prop = attrs.get("property", "")
+        content = attrs.get("content", "")
+        if prop == "og:title" and content:
+            self.og_title = content.removesuffix(" - Devpost")
+        if prop == "og:description" and content and self.description is None:
+            self.description = content
+        if prop == "og:image" and content:
+            image_url = self._normalize_url(content)
+            if image_url:
+                self.hero_image = image_url
+                self._add_image(image_url)
+        if attrs.get("name") == "keywords" and content:
+            for value in content.split(","):
+                self._add_tag(value)
+
+    def _finalize_link(self) -> None:
+        if self._active_link is None:
+            return
+
+        href = self._normalize_url(self._active_link.get("href", "").strip())
+        label = self._active_link.get("text", "").strip() or None
+        self._active_link = None
+
+        if not href:
+            return
+        parsed: ParseResult = urlparse(href)
+        domain = parsed.netloc.lower().replace("www.", "") if parsed.netloc else None
+        is_github = bool(domain and domain.endswith("github.com"))
+        link = ExternalLink(url=href, label=label, domain=domain, is_github=is_github)
+        if all(existing.url != link.url for existing in self.links):
+            self.links.append(link)
+        if is_github and href not in self.github_urls:
+            self.github_urls.append(href)
+
+    def _finalize_creator_profile(self) -> None:
+        if self._active_creator_profile is None:
+            return
+
+        name = self._active_creator_profile.get("name", "").strip()
+        profile_url = self._normalize_url(self._active_creator_profile.get("href", "").strip())
+        photo = self._normalize_url(self._active_creator_profile.get("photo", "").strip())
+        self._active_creator_profile = None
+
+        if not name:
+            return
+
+        creator = CreatorProfile(name=name, profile_url=profile_url, photo=photo)
+        if all(existing.name != creator.name or existing.profile_url != creator.profile_url for existing in self.creator_profiles):
+            self.creator_profiles.append(creator)
+        if name not in self.creators:
+            self.creators.append(name)
+
+    def _normalize_url(self, raw_url: str) -> str:
+        if not raw_url:
+            return ""
+        value = raw_url.strip()
+        if value.startswith("//"):
+            return f"https:{value}"
+        if value.startswith("http://") or value.startswith("https://"):
+            return value
+        return urljoin(self.source_url, value)
+
+    def _add_image(self, image_url: str) -> None:
+        lowered = image_url.lower()
+        if any(token in lowered for token in ("favicon", "avatar", "gravatar", "/icons/", "logo.svg")):
+            return
+        if image_url not in self.image_urls:
+            self.image_urls.append(image_url)
+
+    def _finalize_tag(self) -> None:
+        if self._active_tag_text is None:
+            return
+        self._add_tag(self._active_tag_text)
+        self._active_tag_text = None
+
+    def _add_tag(self, raw_value: str) -> None:
+        value = " ".join(raw_value.split()).strip()
+        if not value:
+            return
+        lowered = value.lower()
+        if lowered in {"built with", "try it out", "created by"}:
+            return
+        if all(existing.lower() != lowered for existing in self.tags):
+            self.tags.append(value)

devpost_api/py.typed

@@ -0,0 +1 @@
+