async_linkedinlib 0.2.0__py3-none-any.whl

async_linkedinlib/models/__init__.py

@@ -0,0 +1,155 @@
+"""Models public exports."""
+
+from .comments import Comment  # One comment or reply.
+from .comments import CommentSort  # Most relevant or most recent comments.
+from .comments import Mention  # A tagged member inside comment text.
+from .content import Author  # Member or company shown on a post or comment.
+from .content import Poll  # A poll attached to a post.
+from .content import PollOption  # One poll choice and its vote state.
+from .content import Post  # One feed update.
+from .content import ReactionType  # Like, Celebrate, Support, Love, Insightful, Funny.
+from .content import SocialCounts  # Reaction, comment and repost totals.
+from .feed import CompanyContent  # Which company page posts to list.
+from .feed import FeedSort  # Top or recent main feed.
+from .feed import ProfileActivity  # A member's posts, comments or reactions.
+from .feed import ReactionSort  # Order of a reactions list.
+from .feed import Reactor  # Who reacted to a post, and how.
+from .feed import SavedPost  # One entry of the saved-posts list.
+from .jobs import Job  # One job posting as a seeker sees it.
+from .jobs import TrackedJob  # One entry of the My jobs lists.
+from .jobs import TrackedStatus  # Saved, in progress, applied or archived.
+from .jobs import WorkplaceType  # On-site, remote or hybrid.
+from .jobs_apply import ApplicationForm  # An Easy Apply form: pages, questions, resumes.
+from .jobs_apply import ApplicationStatus  # Result of a submitted application.
+from .jobs_apply import FileQuestion  # A file slot such as the resume.
+from .jobs_apply import FormPage  # One page of an Easy Apply form.
+from .jobs_apply import Option  # One choice of a question.
+from .jobs_apply import Question  # One Easy Apply question.
+from .jobs_apply import QuestionKind  # Text, number, single choice, dropdown, checkbox.
+from .jobs_apply import Resume  # A resume offered from earlier applications.
+from .jobs_apply import Submission  # A checked application body, not yet sent.
+from .jobs_apply import UploadedFile  # A stored file, ready to attach.
+from .member import Member  # Verified member identity.
+from .pagination import Cursor  # Continues the request that produced a page.
+from .pagination import Page  # One page of results.
+from .posts import CommentScope  # Who may comment on a post.
+from .posts import Document  # A document attachment.
+from .posts import Image  # An image attachment.
+from .posts import LinkPreview  # A link attachment.
+from .posts import MediaKind  # Image, video or document upload.
+from .posts import NewPoll  # A poll to publish.
+from .posts import PollDuration  # How long a new poll runs.
+from .posts import UploadedMedia  # An uploaded file, ready to attach.
+from .posts import Video  # A video attachment.
+from .posts import Visibility  # Anyone or connections only.
+from .posts_results import MediaStatus  # Processing state of an upload.
+from .posts_results import Repost  # An instant repost.
+from .posts_results import ScheduledPost  # One scheduled post.
+from .posts_results import SharedPost  # A published or scheduled post.
+from .search import Filter  # One available search filter.
+from .search import FilterOption  # One suggested filter value.
+from .search import PersonResult  # A person in search results.
+from .search import ResultGroup  # One block of blended results.
+from .search import SearchResult  # A company, group, school, event, course or product.
+from .search import Suggestion  # A typeahead match; its id is a filter value.
+from .search import TypeaheadKind  # What a typeahead looks up.
+from .search import Vertical  # Which kind of result a search returns.
+from .search_filters import CompanyFilters  # Company search filters.
+from .search_filters import CompanySize  # Company size buckets.
+from .search_filters import ContentType  # Post search content types.
+from .search_filters import CourseFilters  # Course search filters.
+from .search_filters import CourseLength  # Course length buckets.
+from .search_filters import CourseLevel  # Course levels.
+from .search_filters import DatePosted  # Post search date ranges.
+from .search_filters import Network  # 1st, 2nd and 3rd+ connections.
+from .search_filters import PeopleFilters  # People search filters.
+from .search_filters import PostedBy  # Post search author scope.
+from .search_filters import PostFilters  # Post search filters.
+from .search_filters import PostSort  # Post search order.
+from .search_filters import ProductFilters  # Product search filters.
+from .search_filters import ServiceFilters  # Service search filters.
+from .search_jobs import Commitment  # Employer commitments filter.
+from .search_jobs import ExperienceLevel  # Job seniority filter.
+from .search_jobs import JobDatePosted  # Job posting date ranges.
+from .search_jobs import JobFilters  # Job search filters.
+from .search_jobs import JobResult  # One job card in search results.
+from .search_jobs import JobSort  # Job search order.
+from .search_jobs import JobType  # Full-time, part-time, contract and more.
+
+__all__ = [
+    "ApplicationForm",
+    "ApplicationStatus",
+    "Author",
+    "Comment",
+    "CommentScope",
+    "CommentSort",
+    "Commitment",
+    "CompanyContent",
+    "CompanyFilters",
+    "CompanySize",
+    "ContentType",
+    "CourseFilters",
+    "CourseLength",
+    "CourseLevel",
+    "Cursor",
+    "DatePosted",
+    "Document",
+    "ExperienceLevel",
+    "FeedSort",
+    "FileQuestion",
+    "Filter",
+    "FilterOption",
+    "FormPage",
+    "Image",
+    "Job",
+    "JobDatePosted",
+    "JobFilters",
+    "JobResult",
+    "JobSort",
+    "JobType",
+    "LinkPreview",
+    "MediaKind",
+    "MediaStatus",
+    "Member",
+    "Mention",
+    "Network",
+    "NewPoll",
+    "Option",
+    "Page",
+    "PeopleFilters",
+    "PersonResult",
+    "Poll",
+    "PollDuration",
+    "PollOption",
+    "Post",
+    "PostFilters",
+    "PostSort",
+    "PostedBy",
+    "ProductFilters",
+    "ProfileActivity",
+    "Question",
+    "QuestionKind",
+    "ReactionSort",
+    "ReactionType",
+    "Reactor",
+    "Repost",
+    "ResultGroup",
+    "Resume",
+    "SavedPost",
+    "ScheduledPost",
+    "SearchResult",
+    "ServiceFilters",
+    "SharedPost",
+    "SocialCounts",
+    "Submission",
+    "Suggestion",
+    "TrackedJob",
+    "TrackedStatus",
+    "TypeaheadKind",
+    "UploadedFile",
+    "UploadedMedia",
+    "Vertical",
+    "Video",
+    "Visibility",
+    "WorkplaceType",
+]

async_linkedinlib/models/_json.py

@@ -0,0 +1,65 @@
+"""Small readers for Voyager JSON; absent or mistyped fields read as None."""
+
+from datetime import UTC
+from datetime import datetime
+from typing import Any
+from urllib.parse import urlsplit
+
+
+def obj(value: object) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def items(value: object) -> list[dict[str, Any]]:
+    return [item for item in value if isinstance(item, dict)] if isinstance(value, list) else []
+
+
+def dig(value: object, *keys: str) -> Any:
+    """Follow nested object keys; None as soon as one is missing."""
+    for key in keys:
+        if not isinstance(value, dict):
+            return None
+        value = value.get(key)
+    return value
+
+
+def string(value: object, *keys: str) -> str | None:
+    found = dig(value, *keys)
+    return found if isinstance(found, str) else None
+
+
+def integer(value: object, *keys: str) -> int | None:
+    found = dig(value, *keys)
+    return found if type(found) is int else None
+
+
+def boolean(value: object, *keys: str) -> bool | None:
+    found = dig(value, *keys)
+    return found if isinstance(found, bool) else None
+
+
+def text(value: object, *keys: str) -> str | None:
+    """The string of a Voyager TextViewModel ({"text": ...}) at the given path."""
+    return string(value, *keys, "text")
+
+
+def urn_id(urn: str | None) -> str | None:
+    """The last colon-separated part of a simple URN, such as the digits of an activity."""
+    if not urn or "(" in urn:
+        return None
+    return urn.rsplit(":", 1)[-1] or None
+
+
+def public_id(
+    url: str | None, sections: tuple[str, ...] = ("in", "company", "school", "showcase")
+) -> str | None:
+    """The vanity name in a profile or page URL, such as `ada` in linkedin.com/in/ada?x=1."""
+    if not url:
+        return None
+    parts = [part for part in urlsplit(url).path.split("/") if part]
+    return parts[1] if len(parts) >= 2 and parts[0] in sections else None
+
+
+def epoch_ms(millis: int | None) -> datetime | None:
+    """A UTC time from Voyager's epoch milliseconds; zero or absent reads as None."""
+    return datetime.fromtimestamp(millis / 1000, UTC) if millis else None

async_linkedinlib/models/comments.py

@@ -0,0 +1,145 @@
+"""Comments, replies and comment reactions as Voyager's dash `Comment` objects describe them."""
+
+from copy import deepcopy
+from dataclasses import dataclass
+from dataclasses import field
+from enum import StrEnum
+from typing import Any
+
+from ._json import boolean
+from ._json import dig
+from ._json import integer
+from ._json import items
+from ._json import obj
+from ._json import public_id
+from ._json import string
+from ._json import text
+from .content import Author
+from .content import SocialCounts
+
+
+class CommentSort(StrEnum):
+    """The app's two comment orders; the UI labels are in comments."""
+
+    RELEVANCE = "RELEVANCE"  # Most relevant
+    RECENT = "REVERSE_CHRONOLOGICAL"  # Most recent
+
+
+@dataclass(frozen=True, slots=True)
+class Mention:
+    """A tag inside comment or post text: `urn` covers `length` characters from `start`.
+
+    `urn` is a member's profile URN (`urn:li:fsd_profile:<id>`, as `Author.profile_urn`
+    reads it); posts also accept a company (`urn:li:fsd_company:<id>`). Positions count
+    Unicode code points, as the app does; the server silently drops a wrong offset.
+    """
+
+    urn: str
+    start: int
+    length: int
+
+
+@dataclass(frozen=True, slots=True)
+class Comment:
+    """One comment or reply.
+
+    `urn` (`urn:li:comment:(activity:<post>,<id>)`) is the comment's own social thread: every
+    comment operation, reaction and reply addresses it. `entity_urn` is the dash entity form.
+    `post_urn` is the post's thread; `parent_urn` is set on replies. `replies` holds only the
+    preview the server embeds; `Comments.replies()` pages through all of them.
+    `created_at` is in epoch milliseconds. `actions` lists the server's allowed actions,
+    such as `EDIT_COMMENT` and `DELETE`.
+    """
+
+    urn: str
+    entity_urn: str | None
+    post_urn: str | None
+    parent_urn: str | None
+    author: Author | None
+    text: str | None
+    mentions: tuple[Mention, ...]
+    created_at: int | None
+    edited: bool | None
+    pinned: bool | None
+    by_post_author: bool | None
+    counts: SocialCounts
+    actions: tuple[str, ...]
+    can_reply: bool | None = None
+    can_react: bool | None = None
+    hide_action_urn: str | None = None
+    permalink: str | None = None
+    replies: tuple["Comment", ...] = ()
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_json(cls, comment: dict[str, Any]) -> "Comment | None":
+        """Build a comment from a dash `Comment`; None when it has no comment URN."""
+        urn = string(comment, "urn")
+        if not urn or not urn.startswith("urn:li:comment:("):
+            return None
+        social = obj(comment.get("socialDetail"))
+        counts = obj(social.get("totalSocialActivityCounts"))
+        permissions = obj(social.get("socialPermissions"))
+        commenter = comment.get("commenter")
+        replies = (cls.from_json(reply) for reply in items(dig(social, "comments", "elements")))
+        hide_action = string(comment, "hideCommentActionUrn") or string(
+            comment, "hideCommentAction", "entityUrn"
+        )
+        return cls(
+            urn=urn,
+            entity_urn=string(comment, "entityUrn"),
+            post_urn=_post_urn(urn),
+            parent_urn=string(comment, "parentCommentBackendUrn"),
+            author=_author(commenter) if isinstance(commenter, dict) else None,
+            text=text(comment, "commentary"),
+            mentions=_mentions(obj(comment.get("commentary"))),
+            created_at=integer(comment, "createdAt"),
+            edited=boolean(comment, "edited"),
+            pinned=boolean(comment, "pinned"),
+            by_post_author=boolean(commenter, "author"),
+            counts=SocialCounts.from_json(counts),
+            actions=tuple(a for a in comment.get("actions") or () if isinstance(a, str)),
+            can_reply=boolean(permissions, "canPostComments"),
+            can_react=boolean(permissions, "canReact"),
+            hide_action_urn=hide_action,
+            permalink=string(comment, "permalink"),
+            replies=tuple(reply for reply in replies if reply is not None),
+            raw=deepcopy(comment),
+        )
+
+
+def _author(commenter: dict[str, Any]) -> Author:
+    """Read a comment's `commenter`; its shape differs from a feed `ActorComponent`."""
+    actor = obj(commenter.get("actor"))
+    profile = string(actor, "profileUrn", "entityUrn") or string(
+        commenter, "actorUnion", "profileUrn"
+    )
+    subtitle = commenter.get("subtitle")
+    url = string(commenter, "navigationUrl")
+    return Author(
+        urn=string(commenter, "urn"),
+        name=text(commenter, "title"),
+        headline=subtitle if isinstance(subtitle, str) else text(commenter, "subtitle"),
+        profile_urn=profile,
+        public_id=public_id(url),
+        url=url.split("?", 1)[0] if url else None,
+    )
+
+
+def _mentions(commentary: dict[str, Any]) -> tuple[Mention, ...]:
+    found = []
+    for attribute in items(commentary.get("attributesV2")):
+        start, length = integer(attribute, "start"), integer(attribute, "length")
+        detail = obj(attribute.get("detailData"))
+        urn = string(detail, "profileMention", "entityUrn") or string(
+            detail, "profileFullName", "entityUrn"
+        )
+        if urn and start is not None and length is not None:
+            found.append(Mention(urn, start, length))
+    return tuple(found)
+
+
+def _post_urn(comment_urn: str) -> str | None:
+    """The post thread inside `urn:li:comment:(activity:<id>,<comment id>)`."""
+    thread = comment_urn.removeprefix("urn:li:comment:(").rpartition(",")[0]
+    return f"urn:li:{thread}" if thread and "(" not in thread else None

async_linkedinlib/models/content.py

@@ -0,0 +1,207 @@
+"""Posts and their authors as Voyager's feed `Update` objects describe them."""
+
+from copy import deepcopy
+from dataclasses import dataclass
+from dataclasses import field
+from enum import StrEnum
+from typing import Any
+
+from ._json import boolean
+from ._json import dig
+from ._json import integer
+from ._json import items
+from ._json import obj
+from ._json import public_id
+from ._json import string
+from ._json import text
+
+
+class ReactionType(StrEnum):
+    """The app's reaction names; the UI labels are in comments."""
+
+    LIKE = "LIKE"
+    CELEBRATE = "PRAISE"  # Celebrate
+    SUPPORT = "APPRECIATION"  # Support
+    LOVE = "EMPATHY"  # Love
+    INSIGHTFUL = "INTEREST"  # Insightful
+    FUNNY = "ENTERTAINMENT"  # Funny
+
+
+@dataclass(frozen=True, slots=True)
+class Author:
+    """A member or organization shown as a post's or comment's actor."""
+
+    urn: str | None
+    name: str | None
+    headline: str | None = None
+    profile_urn: str | None = None
+    public_id: str | None = None
+    url: str | None = None
+
+    @property
+    def is_company(self) -> bool:
+        return bool(self.urn and self.urn.startswith(("urn:li:company:", "urn:li:organization:")))
+
+    @classmethod
+    def from_actor(cls, actor: dict[str, Any]) -> "Author":
+        """Read an `ActorComponent` (feed updates) or comment `commenter` block."""
+        attributes = items(dig(actor, "name", "attributesV2"))
+        detail = obj(attributes[0].get("detailData")) if attributes else {}
+        profile = obj(detail.get("profileFullName"))
+        url = string(actor, "navigationContext", "actionTarget")
+        return cls(
+            urn=string(actor, "backendUrn"),
+            name=text(actor, "name"),
+            headline=text(actor, "description"),
+            profile_urn=string(profile, "entityUrn"),
+            public_id=public_id(url),
+            url=url.split("?", 1)[0] if url else None,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class SocialCounts:
+    """Reaction, comment and repost totals, and the viewer's own reaction.
+
+    `viewer_reaction` is the viewer's reaction name, such as `PRAISE`, when they reacted.
+    """
+
+    reactions: int = 0
+    comments: int = 0
+    reposts: int = 0
+    by_type: dict[str, int] = field(default_factory=dict)
+    viewer_reacted: bool | None = None
+    viewer_reaction: str | None = None
+
+    @classmethod
+    def from_json(cls, counts: dict[str, Any]) -> "SocialCounts":
+        by_type = {
+            entry["reactionType"]: entry["count"]
+            for entry in items(counts.get("reactionTypeCounts"))
+            if isinstance(entry.get("reactionType"), str) and type(entry.get("count")) is int
+        }
+        return cls(
+            reactions=integer(counts, "numLikes") or 0,
+            comments=integer(counts, "numComments") or 0,
+            reposts=integer(counts, "numShares") or 0,
+            by_type=by_type,
+            viewer_reacted=boolean(counts, "liked"),
+            viewer_reaction=string(counts, "reacted"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class PollOption:
+    """One poll choice; `urn` is what `Feed.vote` and `Feed.unvote` take."""
+
+    urn: str | None
+    text: str | None
+    votes: int | None = None
+    voted: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class Poll:
+    """A post's poll: its question, options with vote counts, and whether it closed."""
+
+    question: str | None
+    options: tuple[PollOption, ...]
+    voters: int | None = None
+    closed: bool | None = None
+    multi_select: bool | None = None
+
+    @classmethod
+    def from_component(cls, poll: dict[str, Any]) -> "Poll":
+        """Read a `PollComponent`; summaries line up with options by position, as in the app."""
+        summary = obj(poll.get("pollSummary"))
+        totals = items(summary.get("pollOptionSummaries"))
+        chosen = summary.get("votedPollOptionUrns")
+        voted = (
+            {urn for urn in chosen if isinstance(urn, str)} if isinstance(chosen, list) else set()
+        )
+        options = []
+        for index, option in enumerate(items(poll.get("pollOptions"))):
+            urn = string(option, "pollOptionUrn")
+            votes = integer(totals[index], "voteCount") if index < len(totals) else None
+            options.append(PollOption(urn, text(option, "option"), votes, urn in voted))
+        return cls(
+            question=text(poll, "question"),
+            options=tuple(options),
+            voters=integer(summary, "uniqueVotersCount"),
+            closed=boolean(summary, "closed"),
+            multi_select=boolean(poll, "multiSelect"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Post:
+    """One feed update.
+
+    `urn` is the post's social thread (an activity or ugcPost URN), which reactions and
+    comments address. `activity_urn` is the feed activity, which differs when the update is
+    a "liked this" or similar context around someone else's post. `update_urn` is the feed
+    update itself (`urn:li:fsd_update:(...)`), which hiding addresses. `share_url` is the
+    post's public link.
+    """
+
+    urn: str
+    activity_urn: str | None
+    share_urn: str | None
+    author: Author | None
+    text: str | None
+    age: str | None
+    visibility: str | None
+    context: str | None
+    content_type: str | None
+    counts: SocialCounts
+    can_react: bool | None = None
+    can_comment: bool | None = None
+    can_share: bool | None = None
+    reshared: "Post | None" = None
+    update_urn: str | None = None
+    share_url: str | None = None
+    poll: Poll | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_update(cls, update: dict[str, Any]) -> "Post | None":
+        """Build a post from an `Update`; None for modules such as recommendations.
+
+        The full-screen video layout carries the actor and commentary inside its component
+        instead of on the update, so both places are read.
+        """
+        social = obj(update.get("socialDetail"))
+        activity = string(update, "metadata", "backendUrn")
+        urn = string(social, "threadUrn") or activity
+        content = obj(update.get("content"))
+        video = obj(content.get("largeSingleVideoComponent"))
+        actor = update.get("actor") or video.get("actor")
+        if not urn or not isinstance(actor, dict):
+            return None
+        kinds = [key for key, value in content.items() if value and key.endswith("Component")]
+        age = text(actor, "subDescription")
+        reshared = update.get("resharedUpdate")
+        permissions = obj(social.get("socialPermissions"))
+        poll = content.get("pollComponent")
+        # The link's query names the viewer as the sharer (rcm=...), so only the path is kept.
+        share_url = string(update, "socialContent", "shareUrl")
+        return cls(
+            urn=urn,
+            activity_urn=activity,
+            share_urn=string(update, "metadata", "shareUrn"),
+            author=Author.from_actor(actor),
+            text=text(update, "commentary", "text") or text(video, "commentary"),
+            age=(age.split("•", 1)[0].strip() or None) if age else None,
+            visibility=string(update, "metadata", "shareAudience"),
+            context=text(update, "header", "text"),
+            content_type=kinds[0].removesuffix("Component") if kinds else None,
+            counts=SocialCounts.from_json(obj(social.get("totalSocialActivityCounts"))),
+            can_react=boolean(permissions, "canReact"),
+            can_comment=boolean(permissions, "canPostComments"),
+            can_share=boolean(permissions, "canShare"),
+            reshared=cls.from_update(reshared) if isinstance(reshared, dict) else None,
+            update_urn=string(update, "entityUrn"),
+            share_url=share_url.split("?", 1)[0] if share_url else None,
+            poll=Poll.from_component(poll) if isinstance(poll, dict) else None,
+            raw=deepcopy(update),
+        )