socially 0.2.0__tar.gz

socially-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.Python
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.idea/
+.vscode/
+.DS_Store

socially-0.2.0/LICENSE

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

socially-0.2.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: socially
+Version: 0.2.0
+Summary: Authless social media user lookup — X, TikTok, Instagram, GitHub, Reddit, Bluesky, Mastodon, YouTube
+Project-URL: Homepage, https://github.com/lmaohi7181828/socially
+Project-URL: Repository, https://github.com/lmaohi7181828/socially
+Project-URL: Issues, https://github.com/lmaohi7181828/socially/issues
+Author: socially
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bluesky,github,instagram,mastodon,osint,reddit,social,tiktok,twitter,x,youtube
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: curl-cffi>=0.7; extra == 'dev'
+Requires-Dist: orjson>=3.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: fast
+Requires-Dist: curl-cffi>=0.7; extra == 'fast'
+Requires-Dist: orjson>=3.10; extra == 'fast'
+Description-Content-Type: text/markdown
+
+# socially
+
+Authless multi-platform user lookup for Python.
+
+**X · TikTok · Instagram · GitHub · Reddit · Bluesky · Mastodon · YouTube**
+
+No API keys. No login. Normalized `User` + full `raw` payload.
+
+X user lookup follows the guest GraphQL pattern used by [xtekky/x-noauth-api](https://github.com/xtekky/x-noauth-api) (`UserByScreenName`, public bearer + guest token, feature flags).
+
+## Install
+
+```bash
+pip install socially
+# or with speed extras:
+pip install "socially[fast]"
+```
+
+From source:
+
+```bash
+pip install -e ".[fast]"
+```
+
+`fast` extra: `orjson` + `curl_cffi` (TLS fingerprint).
+
+## Usage
+
+```python
+from socially import Socially, lookup
+
+u = lookup("tiktok", "tiktok")
+print(u.username, u.followers, u.display_name)
+
+u = lookup("bluesky", "jay.bsky.team")
+print(u.id, u.followers)
+
+s = Socially()
+print(s.platforms())
+results = s.lookup_many("nasa", platforms=["github", "youtube", "bluesky"])
+```
+
+## Platforms
+
+| Name | Authless method |
+|------|-----------------|
+| `x` / `twitter` | Guest token + GraphQL `UserByScreenName` (xtekky-style) |
+| `tiktok` | Profile HTML `__UNIVERSAL_DATA_FOR_REHYDRATION__` |
+| `instagram` / `ig` | `web_profile_info` |
+| `github` / `gh` | Public REST `/users/{user}` |
+| `reddit` | `/user/{user}/about.json` |
+| `bluesky` / `bsky` | `app.bsky.actor.getProfile` |
+| `mastodon` | `/api/v1/accounts/lookup` (`user@instance`) |
+| `youtube` / `yt` | Channel `@handle` `ytInitialData` + og meta |
+
+## User fields
+
+`platform`, `id`, `username`, `display_name`, `bio`, `url`, `avatar_url`, `banner_url`,  
+`followers`, `following`, `posts`, `likes`, `verified`, `protected`, `location`, `website`, `created_at`, `raw`
+
+## Publish (maintainers)
+
+1. Create a PyPI API token (Account settings → API tokens).
+2. GitHub repo **Settings → Secrets and variables → Actions** → New secret:
+   - Name: `PYPI_API_TOKEN`
+   - Value: `pypi-...` (full token; never commit it)
+3. Optional: GitHub **Environments** → create `pypi` (workflow references it).
+4. Ship a release by tag:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+`.github/workflows/publish.yml` builds the wheel/sdist and runs `twine upload`.
+
+Manual: **Actions → Publish to PyPI → Run workflow**.
+
+## Notes
+
+Public data only. Some hosts rate-limit datacenter IPs (Instagram, Reddit). Respect each site’s ToS.
+
+## License
+
+MIT

socially-0.2.0/README.md

@@ -0,0 +1,85 @@
+# socially
+
+Authless multi-platform user lookup for Python.
+
+**X · TikTok · Instagram · GitHub · Reddit · Bluesky · Mastodon · YouTube**
+
+No API keys. No login. Normalized `User` + full `raw` payload.
+
+X user lookup follows the guest GraphQL pattern used by [xtekky/x-noauth-api](https://github.com/xtekky/x-noauth-api) (`UserByScreenName`, public bearer + guest token, feature flags).
+
+## Install
+
+```bash
+pip install socially
+# or with speed extras:
+pip install "socially[fast]"
+```
+
+From source:
+
+```bash
+pip install -e ".[fast]"
+```
+
+`fast` extra: `orjson` + `curl_cffi` (TLS fingerprint).
+
+## Usage
+
+```python
+from socially import Socially, lookup
+
+u = lookup("tiktok", "tiktok")
+print(u.username, u.followers, u.display_name)
+
+u = lookup("bluesky", "jay.bsky.team")
+print(u.id, u.followers)
+
+s = Socially()
+print(s.platforms())
+results = s.lookup_many("nasa", platforms=["github", "youtube", "bluesky"])
+```
+
+## Platforms
+
+| Name | Authless method |
+|------|-----------------|
+| `x` / `twitter` | Guest token + GraphQL `UserByScreenName` (xtekky-style) |
+| `tiktok` | Profile HTML `__UNIVERSAL_DATA_FOR_REHYDRATION__` |
+| `instagram` / `ig` | `web_profile_info` |
+| `github` / `gh` | Public REST `/users/{user}` |
+| `reddit` | `/user/{user}/about.json` |
+| `bluesky` / `bsky` | `app.bsky.actor.getProfile` |
+| `mastodon` | `/api/v1/accounts/lookup` (`user@instance`) |
+| `youtube` / `yt` | Channel `@handle` `ytInitialData` + og meta |
+
+## User fields
+
+`platform`, `id`, `username`, `display_name`, `bio`, `url`, `avatar_url`, `banner_url`,  
+`followers`, `following`, `posts`, `likes`, `verified`, `protected`, `location`, `website`, `created_at`, `raw`
+
+## Publish (maintainers)
+
+1. Create a PyPI API token (Account settings → API tokens).
+2. GitHub repo **Settings → Secrets and variables → Actions** → New secret:
+   - Name: `PYPI_API_TOKEN`
+   - Value: `pypi-...` (full token; never commit it)
+3. Optional: GitHub **Environments** → create `pypi` (workflow references it).
+4. Ship a release by tag:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+`.github/workflows/publish.yml` builds the wheel/sdist and runs `twine upload`.
+
+Manual: **Actions → Publish to PyPI → Run workflow**.
+
+## Notes
+
+Public data only. Some hosts rate-limit datacenter IPs (Instagram, Reddit). Respect each site’s ToS.
+
+## License
+
+MIT

socially-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "socially"
+version = "0.2.0"
+description = "Authless social media user lookup — X, TikTok, Instagram, GitHub, Reddit, Bluesky, Mastodon, YouTube"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "socially" }]
+keywords = [
+  "social", "twitter", "x", "tiktok", "instagram", "github",
+  "reddit", "bluesky", "mastodon", "youtube", "osint",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+fast = ["orjson>=3.10", "curl_cffi>=0.7"]
+dev = ["pytest>=8.0", "orjson>=3.10", "curl_cffi>=0.7"]
+
+[project.urls]
+Homepage = "https://github.com/lmaohi7181828/socially"
+Repository = "https://github.com/lmaohi7181828/socially"
+Issues = "https://github.com/lmaohi7181828/socially/issues"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/socially",
+  "tests",
+  "README.md",
+  "LICENSE",
+  "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

socially-0.2.0/src/socially/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from .client import Socially
+from .exceptions import (
+    PlatformError,
+    RateLimited,
+    RequestError,
+    SociallyError,
+    UserNotFound,
+)
+from .models.user import User
+from .platforms import PLATFORMS
+
+__all__ = [
+    "PLATFORMS",
+    "PlatformError",
+    "RateLimited",
+    "RequestError",
+    "Socially",
+    "SociallyError",
+    "User",
+    "UserNotFound",
+    "lookup",
+]
+
+__version__ = "0.2.0"
+
+
+def lookup(platform: str, username: str) -> User:
+    return Socially().lookup(platform, username)

socially-0.2.0/src/socially/__init__.pyi

@@ -0,0 +1,15 @@
+from .client import Socially as Socially
+from .exceptions import (
+    PlatformError as PlatformError,
+    RateLimited as RateLimited,
+    RequestError as RequestError,
+    SociallyError as SociallyError,
+    UserNotFound as UserNotFound,
+)
+from .models.user import User as User
+from .platforms import PLATFORMS as PLATFORMS
+
+__version__: str
+__all__: list[str]
+
+def lookup(platform: str, username: str) -> User: ...

socially-0.2.0/src/socially/client.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Iterable
+
+from .exceptions import SociallyError
+from .models.user import User
+from .platforms import PLATFORMS, Platform
+
+_ALIASES = {
+    "twitter": "x",
+    "ig": "instagram",
+    "gh": "github",
+    "bsky": "bluesky",
+    "yt": "youtube",
+}
+
+
+class Socially:
+    __slots__ = ("_providers",)
+
+    def __init__(self, platforms: Iterable[str] | None = None) -> None:
+        self._providers: dict[str, Platform] = {}
+        names = platforms if platforms is not None else PLATFORMS.keys()
+        seen: set[type[Platform]] = set()
+        for name in names:
+            key = name.lower().strip()
+            cls = PLATFORMS.get(key)
+            if cls is None or cls in seen:
+                continue
+            seen.add(cls)
+            self._providers[cls.name] = cls()
+
+    def platforms(self) -> list[str]:
+        return sorted(self._providers)
+
+    def lookup(self, platform: str, username: str) -> User:
+        key = _ALIASES.get(platform.lower().strip(), platform.lower().strip())
+        provider = self._providers.get(key)
+        if provider is None:
+            cls = PLATFORMS.get(key)
+            if cls is None:
+                raise SociallyError(f"unknown platform: {platform}")
+            provider = cls()
+            self._providers[cls.name] = provider
+            key = cls.name
+        return provider.lookup(username)
+
+    def lookup_many(
+        self,
+        username: str,
+        platforms: Iterable[str] | None = None,
+    ) -> dict[str, User | BaseException]:
+        targets = list(platforms) if platforms is not None else self.platforms()
+        out: dict[str, User | BaseException] = {}
+        for p in targets:
+            try:
+                out[p] = self.lookup(p, username)
+            except BaseException as e:
+                out[p] = e
+        return out

socially-0.2.0/src/socially/client.pyi

@@ -0,0 +1,15 @@
+from collections.abc import Iterable
+from typing import BaseException
+
+from .models.user import User
+from .platforms.base import Platform
+
+class Socially:
+    def __init__(self, platforms: Iterable[str] | None = ...) -> None: ...
+    def platforms(self) -> list[str]: ...
+    def lookup(self, platform: str, username: str) -> User: ...
+    def lookup_many(
+        self,
+        username: str,
+        platforms: Iterable[str] | None = ...,
+    ) -> dict[str, User | BaseException]: ...

socially-0.2.0/src/socially/exceptions.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+
+class SociallyError(Exception):
+    pass
+
+
+class PlatformError(SociallyError):
+    def __init__(self, platform: str, message: str) -> None:
+        self.platform = platform
+        super().__init__(f"[{platform}] {message}")
+
+
+class UserNotFound(PlatformError):
+    pass
+
+
+class RateLimited(PlatformError):
+    pass
+
+
+class RequestError(PlatformError):
+    pass

socially-0.2.0/src/socially/exceptions.pyi

@@ -0,0 +1,9 @@
+class SociallyError(Exception): ...
+
+class PlatformError(SociallyError):
+    platform: str
+    def __init__(self, platform: str, message: str) -> None: ...
+
+class UserNotFound(PlatformError): ...
+class RateLimited(PlatformError): ...
+class RequestError(PlatformError): ...

socially-0.2.0/src/socially/http.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import orjson as _json
+
+    def loads(data: bytes | str) -> Any:
+        if isinstance(data, str):
+            data = data.encode()
+        return _json.loads(data)
+
+    def dumps(obj: Any) -> str:
+        return _json.dumps(obj).decode()
+
+except ImportError:
+    import json as _json
+
+    def loads(data: bytes | str) -> Any:
+        if isinstance(data, bytes):
+            data = data.decode()
+        return _json.loads(data)
+
+    def dumps(obj: Any) -> str:
+        return _json.dumps(obj, separators=(",", ":"))
+
+UA = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/131.0.0.0 Safari/537.36"
+)
+
+
+def session(impersonate: str | None = "chrome"):
+    try:
+        from curl_cffi import requests as creq
+
+        return creq.Session(impersonate=impersonate or "chrome")
+    except ImportError:
+        import requests
+
+        s = requests.Session()
+        s.headers["User-Agent"] = UA
+        return s
+
+
+def get(
+    url: str,
+    *,
+    headers: dict[str, str] | None = None,
+    timeout: float = 15.0,
+    impersonate: str | None = "chrome",
+) -> Any:
+    s = session(impersonate)
+    h = {"User-Agent": UA, "Accept": "*/*"}
+    if headers:
+        h.update(headers)
+    return s.get(url, headers=h, timeout=timeout)
+
+
+def post(
+    url: str,
+    *,
+    headers: dict[str, str] | None = None,
+    data: Any = None,
+    json_body: Any = None,
+    timeout: float = 15.0,
+    impersonate: str | None = "chrome",
+) -> Any:
+    s = session(impersonate)
+    h = {"User-Agent": UA, "Accept": "*/*"}
+    if headers:
+        h.update(headers)
+    kwargs: dict[str, Any] = {"headers": h, "timeout": timeout}
+    if json_body is not None:
+        kwargs["data"] = dumps(json_body).encode() if not isinstance(json_body, (str, bytes)) else json_body
+        h.setdefault("Content-Type", "application/json")
+    elif data is not None:
+        kwargs["data"] = data
+    return s.post(url, **kwargs)

socially-0.2.0/src/socially/models/__init__.py

@@ -0,0 +1,3 @@
+from .user import User
+
+__all__ = ["User"]

socially-0.2.0/src/socially/models/user.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class User:
+    platform: str
+    id: str | None = None
+    username: str | None = None
+    display_name: str | None = None
+    bio: str | None = None
+    url: str | None = None
+    avatar_url: str | None = None
+    banner_url: str | None = None
+    followers: int | None = None
+    following: int | None = None
+    posts: int | None = None
+    likes: int | None = None
+    verified: bool | None = None
+    protected: bool | None = None
+    location: str | None = None
+    website: str | None = None
+    created_at: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

socially-0.2.0/src/socially/models/user.pyi

@@ -0,0 +1,44 @@
+from typing import Any
+
+class User:
+    platform: str
+    id: str | None
+    username: str | None
+    display_name: str | None
+    bio: str | None
+    url: str | None
+    avatar_url: str | None
+    banner_url: str | None
+    followers: int | None
+    following: int | None
+    posts: int | None
+    likes: int | None
+    verified: bool | None
+    protected: bool | None
+    location: str | None
+    website: str | None
+    created_at: str | None
+    raw: dict[str, Any]
+
+    def __init__(
+        self,
+        platform: str,
+        id: str | None = ...,
+        username: str | None = ...,
+        display_name: str | None = ...,
+        bio: str | None = ...,
+        url: str | None = ...,
+        avatar_url: str | None = ...,
+        banner_url: str | None = ...,
+        followers: int | None = ...,
+        following: int | None = ...,
+        posts: int | None = ...,
+        likes: int | None = ...,
+        verified: bool | None = ...,
+        protected: bool | None = ...,
+        location: str | None = ...,
+        website: str | None = ...,
+        created_at: str | None = ...,
+        raw: dict[str, Any] = ...,
+    ) -> None: ...
+    def to_dict(self) -> dict[str, Any]: ...

socially-0.2.0/src/socially/platforms/__init__.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from .base import Platform
+from .bluesky import Bluesky
+from .github import GitHub
+from .instagram import Instagram
+from .mastodon import Mastodon
+from .reddit import Reddit
+from .tiktok import TikTok
+from .x import X
+from .youtube import YouTube
+
+PLATFORMS: dict[str, type[Platform]] = {
+    "x": X,
+    "twitter": X,
+    "tiktok": TikTok,
+    "instagram": Instagram,
+    "ig": Instagram,
+    "github": GitHub,
+    "gh": GitHub,
+    "reddit": Reddit,
+    "bluesky": Bluesky,
+    "bsky": Bluesky,
+    "mastodon": Mastodon,
+    "youtube": YouTube,
+    "yt": YouTube,
+}
+
+__all__ = [
+    "PLATFORMS",
+    "Platform",
+    "X",
+    "TikTok",
+    "Instagram",
+    "GitHub",
+    "Reddit",
+    "Bluesky",
+    "Mastodon",
+    "YouTube",
+]

socially-0.2.0/src/socially/platforms/base.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..models.user import User
+
+
+class Platform(ABC):
+    name: str
+
+    @abstractmethod
+    def lookup(self, username: str) -> User:
+        ...

socially-0.2.0/src/socially/platforms/base.pyi

@@ -0,0 +1,8 @@
+from abc import ABC, abstractmethod
+
+from ..models.user import User
+
+class Platform(ABC):
+    name: str
+    @abstractmethod
+    def lookup(self, username: str) -> User: ...