lobstr 0.5.0__tar.gz

lobstr-0.5.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.3
+Name: lobstr
+Version: 0.5.0
+Summary: unofficial API client for lobste.rs
+Keywords: lobste.rs,lobsters,asyncio,httpx,pydantic
+Author: kavin
+Author-email: kavin <kavin.srinivasan2@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+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: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/kavin81/lobstr
+Project-URL: Issues, https://github.com/kavin81/lobstr/issues
+Project-URL: Repository, https://github.com/kavin81/lobstr
+Description-Content-Type: text/markdown
+
+# lobstr
+
+`lobstr` is an unofficial async-first object-oriented api wrapper for [lobste.rs](https://lobste.rs/).
+
+the library only supports `GET` requests or read operations.
+It plans to support the following objects
+- [x] feeds (homepage, newest, by tags, etc)
+- [x] stories (the post + comments)
+- [x] comments (info about a singular comment)
+- [x] tags (info regarding a tag, list of all tags)
+- [ ] search (search for stories, comments, users)
+
+## Table of Contents
+
+* [Features](#features)
+* [Installation](#installation)
+* [Quick Start](#quick-start)
+* [Documentation](#documentation)
+* [License](#license)
+
+## Features
+
+* Async-first API built on `httpx`
+* Fully typed Pydantic models
+* Well-documented sdk with docstrings
+
+## Installation
+
+> Requires Python 3.10 or higher.
+
+### pip
+
+```bash
+pip install lobstr
+```
+
+### uv
+
+```bash
+uv add lobstr
+```
+
+### Poetry
+
+```bash
+poetry add lobstr
+```
+
+### Pipenv
+
+```bash
+pipenv install lobstr
+```
+
+## Quick Start
+
+### Fetch a Story
+
+```python
+import asyncio
+from lobstr import Lobster
+
+async def main():
+    async with Lobster() as lob:
+        story = await lob.story(short_id="ishgbs")
+        print(story.title) # title of the story
+        print(story.username) # author's username
+        print(story.article_url) # article attached to the story
+
+asyncio.run(main())
+```
+
+### Fetch Hottest Stories
+
+```python
+import asyncio
+from lobstr import Lobster
+
+async def main():
+    async with Lobster() as lob:
+        stories = await lob.feeds.hot()
+        for story in stories[:5]: # print the top 5 hottest stories
+            print(story.title) # title of the story
+            print(story.username) # author's username
+            print(story.article_url) # article attached to the story
+
+asyncio.run(main())
+```
+
+
+## Documentation
+
+Complete documentation, API reference, guides, and examples are available at:
+
+**https://kavin81.github.io/lobstr**
+
+For lobste.rs API documentation, [`API_SPEC.md`](./API_SPEC.md).
+## License
+
+- [MIT](LICENSE)

lobstr-0.5.0/README.md

@@ -0,0 +1,100 @@
+# lobstr
+
+`lobstr` is an unofficial async-first object-oriented api wrapper for [lobste.rs](https://lobste.rs/).
+
+the library only supports `GET` requests or read operations.
+It plans to support the following objects
+- [x] feeds (homepage, newest, by tags, etc)
+- [x] stories (the post + comments)
+- [x] comments (info about a singular comment)
+- [x] tags (info regarding a tag, list of all tags)
+- [ ] search (search for stories, comments, users)
+
+## Table of Contents
+
+* [Features](#features)
+* [Installation](#installation)
+* [Quick Start](#quick-start)
+* [Documentation](#documentation)
+* [License](#license)
+
+## Features
+
+* Async-first API built on `httpx`
+* Fully typed Pydantic models
+* Well-documented sdk with docstrings
+
+## Installation
+
+> Requires Python 3.10 or higher.
+
+### pip
+
+```bash
+pip install lobstr
+```
+
+### uv
+
+```bash
+uv add lobstr
+```
+
+### Poetry
+
+```bash
+poetry add lobstr
+```
+
+### Pipenv
+
+```bash
+pipenv install lobstr
+```
+
+## Quick Start
+
+### Fetch a Story
+
+```python
+import asyncio
+from lobstr import Lobster
+
+async def main():
+    async with Lobster() as lob:
+        story = await lob.story(short_id="ishgbs")
+        print(story.title) # title of the story
+        print(story.username) # author's username
+        print(story.article_url) # article attached to the story
+
+asyncio.run(main())
+```
+
+### Fetch Hottest Stories
+
+```python
+import asyncio
+from lobstr import Lobster
+
+async def main():
+    async with Lobster() as lob:
+        stories = await lob.feeds.hot()
+        for story in stories[:5]: # print the top 5 hottest stories
+            print(story.title) # title of the story
+            print(story.username) # author's username
+            print(story.article_url) # article attached to the story
+
+asyncio.run(main())
+```
+
+
+## Documentation
+
+Complete documentation, API reference, guides, and examples are available at:
+
+**https://kavin81.github.io/lobstr**
+
+For lobste.rs API documentation, [`API_SPEC.md`](./API_SPEC.md).
+## License
+
+- [MIT](LICENSE)

lobstr-0.5.0/lobstr/__init__.py

@@ -0,0 +1,5 @@
+from .client import Lobstr
+
+__all__ = ["Lobstr"]
+
+

lobstr-0.5.0/lobstr/client.py

@@ -0,0 +1,55 @@
+import httpx
+
+from lobstr.services import (
+    CommentService,
+    FeedService,
+    StoryService,
+    UserService,
+    TagService,
+)
+
+from .constants import CONSTANTS
+
+
+class Lobstr:
+    """
+    main client class for interacting with the Lobstr API.
+
+    Attributes:
+        client (httpx.AsyncClient): The HTTP client used for making requests.
+        user (UserService): Service for user-related operations.
+        comment (CommentService): Service for comment-related operations.
+        feed (FeedService): Service for feed-related operations.
+        story (StoryService): Service for story-related operations.
+        tag (TagService): Service for tag-related operations.
+    """
+
+    def __init__(
+        self,
+        base_url: str = CONSTANTS.BASE_URL,
+        timeout: int = CONSTANTS.DEFAULT_TIMEOUT,
+    ) -> None:
+        self.client: httpx.AsyncClient = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=timeout,
+            event_hooks={
+                # "response": [raise_for_status],
+            },
+        )
+
+        self.user = UserService(self.client)
+        self.comment = CommentService(self.client)
+        self.feed = FeedService(self.client)
+        self.story = StoryService(self.client)
+        self.tag = TagService(self.client)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type,
+        exc,
+        tb,
+    ):
+        await self.client.aclose()

lobstr-0.5.0/lobstr/constants.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel
+
+
+class Constants(BaseModel):
+    BASE_URL: str = "https://lobste.rs"
+    DEFAULT_TIMEOUT: int = 10
+
+
+CONSTANTS = Constants()

lobstr-0.5.0/lobstr/exceptions.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from httpx import URL
+
+
+class LobstersError(Exception):
+    """Base exception for the lobste.rs client."""
+
+
+class LobstersAPIError(LobstersError):
+    """Base exception for API-related failures."""
+
+    def __init__(
+        self,
+        *,
+        resource: str,
+        identifier: str | int,
+        endpoint: URL,
+        status_code: int,
+    ) -> None:
+        self.identifier = identifier
+        self.endpoint = endpoint
+        self.status_code = status_code
+
+        identifier_repr = (
+            repr(identifier) if isinstance(identifier, str) else str(identifier)
+        )
+
+        super().__init__(
+            f"{resource} {identifier_repr} not found "
+            f"(GET {endpoint} returned {status_code})"
+        )
+
+
+class ResourceNotFound(LobstersAPIError):
+    """Base exception for missing Lobsters resources."""
+
+    resource_name = "Resource"
+    status_code = 404
+
+    def __init__(
+        self,
+        identifier: str | int,
+        *,
+        endpoint: URL,
+    ) -> None:
+        super().__init__(
+            resource=self.resource_name,
+            identifier=identifier,
+            endpoint=endpoint,
+            status_code=self.status_code,
+        )
+
+
+class StoryNotFound(ResourceNotFound):
+    resource_name = "Story"
+
+    def __init__(self, story_id: str, *, endpoint: URL) -> None:
+        self.story_id = story_id
+        super().__init__(
+            identifier=story_id,
+            endpoint=endpoint,
+        )
+
+
+class CommentNotFound(ResourceNotFound):
+    resource_name = "Comment"
+    status_code = 400
+
+    def __init__(self, comment_id: str, *, endpoint: URL) -> None:
+        self.comment_id = comment_id
+        super().__init__(
+            identifier=comment_id,
+            endpoint=endpoint,
+        )
+
+
+class UserNotFound(ResourceNotFound):
+    resource_name = "User"
+
+    def __init__(self, username: str, *, endpoint: URL) -> None:
+        self.username = username
+        super().__init__(
+            identifier=username,
+            endpoint=endpoint,
+        )
+
+
+class TagNotFound(ResourceNotFound):
+    resource_name = "Tag"
+
+    def __init__(self, tag: str, *, endpoint: URL) -> None:
+        self.tag = tag
+        super().__init__(
+            identifier=tag,
+            endpoint=endpoint,
+        )
+
+
+class FeedPageNotFound(ResourceNotFound):
+    resource_name = "Feed page"
+
+    def __init__(self, page: int, *, endpoint: URL) -> None:
+        self.page = page
+        super().__init__(
+            identifier=page,
+            endpoint=endpoint,
+        )
+
+
+# [x] for story /s/not_found.json -> STATUS_CODE=404
+# [x] for comments /c/not_found.json -> STATUS_CODE=400 , MSG="can't find comment"
+# [x] for feeds /*/page/<page_no>.json -> STATUS_CODE=404
+# [x] for users /~usernamenotfound.json -> STATUS_CODE=404
+# [x] for tags /t/tag_does_not_exist.json -> STATUS_CODE=404

lobstr-0.5.0/lobstr/models/__init__.py

@@ -0,0 +1,18 @@
+from .core import PageMixin
+from .user import User
+from .post import Post
+from .feed import Feed
+from .comment import Comment
+from .story import Story
+from .tag import Tag, Tags
+
+__all__: list[str] = [
+    "PageMixin",
+    "User",
+    "Post",
+    "Feed",
+    "Comment",
+    "Story",
+    "Tag",
+    "Tags",
+]

lobstr-0.5.0/lobstr/models/comment.py

@@ -0,0 +1,73 @@
+from datetime import datetime
+from typing import Optional, Any
+
+from pydantic import BaseModel, Field, ConfigDict, model_validator
+
+from .core import Content, URLPair
+
+
+class Comment(BaseModel):
+    """
+    Represents a comment on a [post](https://lobste.rs/c/szmc6l).
+
+    Attributes:
+        id (str): The unique identifier for the comment.
+        created_at (datetime): The timestamp when the comment was created.
+        edited_at (Optional[datetime]): The timestamp when the comment was last edited, if applicable.
+        is_deleted (bool): Indicates whether the comment has been deleted.
+        is_moderated (bool): Indicates whether the comment has been moderated.
+        score (int): The score of the comment, representing upvotes minus downvotes.
+        flags (int): The number of flags the comment has received.
+        depth (int): The depth of the comment in the thread hierarchy.
+        username (str): The username of the commenter.
+        content (Content): The content of the comment, including both HTML (`.content`) and plain text versions (`.content.plain`).
+        parent (Optional[str]): The ID of the parent comment, if this comment is a reply.
+        url (URLPair): URLs linking to the comment, `url.canonical` and `url.short` versions.
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra="ignore",
+    )
+
+    id: str = Field(validation_alias="short_id")
+
+    created_at: datetime
+    edited_at: Optional[datetime] = Field(
+        default=None,
+        validation_alias="last_edited_at",
+    )
+
+    is_deleted: bool
+    is_moderated: bool
+
+    score: int
+    flags: int
+    depth: int
+
+    username: str = Field(validation_alias="commenting_user")
+
+    content: Content
+
+    parent: Optional[str] = Field(
+        default=None,
+        validation_alias="parent_comment",
+    )
+
+    url: URLPair
+
+    @model_validator(mode="before")
+    @classmethod
+    def comment_preprocessing(cls, data: Any):
+        if isinstance(data, dict):
+            data["content"] = Content(
+                data.pop("comment", ""),
+                data.pop("comment_plain", ""),
+            )
+
+            data["url"] = URLPair(
+                canonical=data.pop("url"),
+                short=data.pop("short_id_url"),
+            )
+
+        return data

lobstr-0.5.0/lobstr/models/core.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+
+@dataclass(frozen=True)
+class URLPair:
+    """
+    dataclass that holds both canonical and short versions of a URL to a resource.
+
+    Attributes:
+        canonical (str): The canonical version of the URL.
+        short (str): The shortened version of the URL.
+    """
+
+    canonical: str
+    short: str
+
+
+class Content(str):
+    """
+    A string subclass that holds both the original content and a plain version of it.
+
+    Attributes:
+        cls/self (str): The original HTML content.
+        plain (str): The plain version of the content.
+    """
+
+    __slots__ = ("plain",)
+
+    def __new__(cls, content: str, plain_content: str):
+        obj = super().__new__(cls, content)
+        obj.plain = plain_content
+        return obj
+
+
+class PageMixin(BaseModel):
+    """Mixin for adding pagination information to a model."""
+
+    page: int = 1

lobstr-0.5.0/lobstr/models/feed.py

@@ -0,0 +1,15 @@
+from .post import Post
+from .core import PageMixin
+from pydantic import Field
+
+
+class Feed(PageMixin):
+    """
+    A Feed is an array of posts along with pagination info
+
+    Attributes:
+        posts (list[Post]): A list of Post objects in the feed
+        page (int): The current page number
+    """
+
+    posts: list[Post] = Field(default_factory=list)

lobstr-0.5.0/lobstr/models/post.py

@@ -0,0 +1,62 @@
+from datetime import datetime
+
+from pydantic import BaseModel, Field, ConfigDict, model_validator
+
+from .core import Content, URLPair
+
+
+class Post(BaseModel):
+    """
+    Represents a post on the lobste.rs [home page](https://lobste.rs).
+
+    Attributes:
+        id (str): The unique identifier for the post.
+        description (Content): The description of the post, including both HTML (`.description`) and plain text versions (`.description.plain`).
+        created_at (datetime): The timestamp when the post was created.
+        title (str): The title of the post.
+        score (int): The score of the post, representing upvotes minus downvotes.
+        flags (int): The number of flags the post has received.
+        tags (list[str]): A list of [tags](https://lobste.rs/tags) associated with the post.
+        comment_count (int): The number of comments on the post.
+        username (str): The username of the poster.
+        article_url (str): The URL of the article linked to the post.
+        url (URLPair): A pair of URLs for the post, including canonical (`.url.canonical`) and short (`.url.short`) versions.
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra="ignore",
+    )
+
+    id: str = Field(validation_alias="short_id")
+    description: Content
+
+    created_at: datetime
+
+    title: str
+    score: int
+    flags: int
+    comment_count: int
+    username: str = Field(validation_alias="submitter_user")
+
+    article_url: str
+    url: URLPair
+
+    tags: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def post_preprocessing(cls, data):
+        if isinstance(data, dict):
+            data["description"] = Content(
+                data.pop("description", ""),
+                data.pop("description_plain", ""),
+            )
+            data["article_url"] = data.pop("url")
+
+            data["url"] = URLPair(
+                canonical=data.pop("comments_url"),
+                short=data.pop("short_id_url"),
+            )
+
+        return data

lobstr-0.5.0/lobstr/models/story.py

@@ -0,0 +1,28 @@
+from typing import List
+
+from pydantic import Field
+
+from .comment import Comment
+from .post import Post
+
+
+class Story(Post):
+    """
+    Represents a [Story](https://lobste.rs/s/109l2t) i.e. A Post & Its comments
+
+    Attributes:
+        id (str): The unique identifier for the post.
+        description (Content): The description of the post, including both HTML (`.description`) and plain text versions (`.description.plain`).
+        created_at (datetime): The timestamp when the post was created.
+        title (str): The title of the post.
+        score (int): The score of the post, representing upvotes minus downvotes.
+        flags (int): The number of flags the post has received.
+        tags (list[str]): A list of [tags](https://lobste.rs/tags) associated with the post.
+        comment_count (int): The number of comments on the post.
+        username (str): The username of the poster.
+        article_url (str): The URL of the article linked to the post.
+        url (URLPair): A pair of URLs for the post, including canonical (`.url.canonical`) and short (`.url.short`) versions.
+        comments (List[Comment]): A list of comments associated with the story
+    """
+
+    comments: List[Comment] = Field(default_factory=list)

lobstr-0.5.0/lobstr/models/tag.py

@@ -0,0 +1,30 @@
+from pydantic import BaseModel, Field, TypeAdapter
+from typing import List
+
+
+class Tag(BaseModel):
+    """
+    Represents metadata related to a [tag](https://lobste.rs/tags).
+
+    Attributes:
+        name (str): The name of the tag.
+        description (str): A brief description of the tag.
+        category (str): The category of the tag.
+        is_privileged (bool): Indicates if the tag needs additional permissions to be used.
+        is_media (bool): Indicates if the tag is related to media content.
+        is_active (bool): Indicates if the tag is currently active.
+        hotness_mod (float): A modifier that affects the "hotness" score of stories (used for home page ranking)
+    """
+
+    name: str = Field(..., alias="tag")
+    description: str
+    category: str
+
+    is_privileged: bool = Field(..., alias="privileged")
+    is_media: bool
+    is_active: bool = Field(..., alias="active")
+
+    hotness_mod: float
+
+
+Tags = TypeAdapter(List[Tag])

lobstr-0.5.0/lobstr/models/user.py

@@ -0,0 +1,31 @@
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    """
+    represents a [user](https://lobste.rs/~pushcx).
+
+    Attributes:
+        username (str): The user's username.
+        karma (int): The user's karma score.
+        about (str): The user's about section.
+        avatar_url (str): The URL of the user's avatar image.
+        created_at (datetime): The date and time when the user was created.
+        is_admin (bool): Whether the user is an admin.
+        is_moderator (bool): Whether the user is a moderator.
+        invited_by_user (Optional[str]): The username of the user who invited this user, if applicable.
+    """
+
+    username: str
+    karma: int
+    about: str
+    avatar_url: str
+
+    created_at: datetime
+
+    is_admin: bool
+    is_moderator: bool
+
+    invited_by_user: Optional[str] = None

lobstr-0.5.0/lobstr/services/__init__.py

@@ -0,0 +1,13 @@
+from .user import UserService
+from .comment import CommentService
+from .feed import FeedService
+from .story import StoryService
+from .tag import TagService
+
+__all__ = [
+    "UserService",
+    "CommentService",
+    "FeedService",
+    "StoryService",
+    "TagService",
+]

lobstr-0.5.0/lobstr/services/comment.py

@@ -0,0 +1,36 @@
+from lobstr.exceptions import CommentNotFound
+
+from .core import BaseService
+from lobstr.models import Comment
+
+
+class CommentService(BaseService):
+    """
+    Service for interacting with the comments API.
+
+    Methods:
+        `get(short_id: str) -> Comment`: Retrieve a comment by its short ID.
+    """
+
+    async def get(self, short_id: str) -> Comment:
+        """
+        Retrieve a comment by its short ID.
+
+        Args:
+            short_id (str): The short ID of the comment to retrieve.
+
+        Returns:
+            Comment: The retrieved comment.
+
+        Raises:
+            CommentNotFound: If the comment with the given short ID does not exist.
+            HTTPError: If the request to the API fails for any other reason.
+        """
+        resp = await self._client.get(f"/c/{short_id}.json")
+        if resp.status_code == 400 and resp.text == "can't find comment":
+            raise CommentNotFound(
+                comment_id=short_id,
+                endpoint=resp.url,
+            )
+        resp.raise_for_status()
+        return Comment.model_validate(resp.json())

lobstr-0.5.0/lobstr/services/core.py

@@ -0,0 +1,6 @@
+import httpx
+
+
+class BaseService:
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self._client = client

lobstr-0.5.0/lobstr/services/feed.py

@@ -0,0 +1,106 @@
+from lobstr.exceptions import FeedPageNotFound
+
+from .core import BaseService
+from lobstr.models import Feed
+
+
+class FeedService(BaseService):
+    """
+    Service for interacting with the feed endpoints of the Lobstr API.
+
+    Methods:
+        `hot(page: int = 1) -> Feed`: Retrieve the hottest posts from the feed.
+        `new(page: int = 1) -> Feed`: Retrieve the newest posts from the feed.
+        `tag(tag: str, page: int = 1) -> Feed`: Retrieve posts associated with a specific tag.
+        `filter(*tag: str, page: int = 1) -> Feed`: Retrieve posts associated with multiple tags.
+    """
+
+    async def _feed(self, endpoint: str, page: int = 1) -> Feed:
+        """
+        Internal method to retrieve feed data from a specific endpoint and page.
+        """
+        resp = await self._client.get(f"{endpoint}/page/{page}.json")
+        if resp.status_code == 404:
+            raise FeedPageNotFound(
+                page=page,
+                endpoint=resp.url,
+            )
+        resp.raise_for_status()
+
+        return Feed.model_validate(
+            {
+                "page": page,
+                "posts": resp.json(),
+            }
+        )
+
+    async def hot(self, page: int = 1) -> Feed:
+        """
+        Retrieve the hottest posts from the feed.
+
+        Args:
+            page (int): The page number to retrieve. Defaults to 1.
+
+        Returns:
+            Feed: The feed object containing the hottest posts for the specified page.
+
+        Raises:
+            FeedPageNotFound: If the specified page does not exist in the feed.
+            HTTPError: If the request to the API fails for any other reason.
+        """
+        resp = await self._feed("/hottest", page)
+        return resp
+
+    async def new(self, page: int = 1) -> Feed:
+        """
+        Retrieve the newest posts from the feed.
+
+        Args:
+            page (int): The page number to retrieve. Defaults to 1.
+
+
+        Returns:
+            Feed: The feed object containing the newest posts for the specified page.
+
+        Raises:
+            FeedPageNotFound: If the specified page does not exist in the feed.
+            HTTPError: If the request to the API fails for any other reason.
+        """
+        resp = await self._feed("/newest", page)
+        return resp
+
+    async def tag(self, tag: str, page: int = 1) -> Feed:
+        """
+        Retrieve posts associated with a specific tag.
+
+        Args:
+            tag (str): The tag to filter posts by.
+            page (int): The page number to retrieve. Defaults to 1.
+
+        Returns:
+            Feed: The feed object containing posts associated with the specified tag for the specified page.
+
+        Raises:
+            FeedPageNotFound: If the specified page does not exist for the given tag in the feed.
+            HTTPError: If the request to the API fails for any other reason.
+        """
+        resp = await self._feed(f"/t/{tag}", page)
+        return resp
+
+    async def filter(self, *tag: str, page: int = 1) -> Feed:
+        """
+        Retrieve posts associated with multiple tags.
+
+        Args:
+            *tag (str): The tags to filter posts by.
+            page (int): The page number to retrieve. Defaults to 1.
+
+        Returns:
+            Feed: The feed object containing posts associated with the specified tags for the specified page.
+
+        Raises:
+            FeedPageNotFound: If the specified page does not exist for the given tags in the feed.
+            HTTPError: If the request to the API fails for any other reason.
+        """
+        resp = await self._feed(f"/t/{','.join(tag)}", page)
+        return resp

lobstr-0.5.0/lobstr/services/story.py

@@ -0,0 +1,35 @@
+from .core import BaseService
+from lobstr.models import Story
+from lobstr.exceptions import StoryNotFound
+
+
+class StoryService(BaseService):
+    """
+    Service for interacting with the story endpoints of the Lobstr API.
+
+    Methods:
+        `get(short_id: str) -> Story`: Retrieve a story by its short ID.
+    """
+
+    async def get(self, short_id: str) -> Story:
+        """
+        Retrieve a story by its short ID.
+
+        Args:
+            short_id (str): The short ID of the story to retrieve.
+
+        Returns:
+            Story: An instance of the Story model representing the retrieved story.
+
+        Raises:
+            StoryNotFound: If the story with the given short ID does not exist.
+            HTTPError: If the request to the API fails for any other reason.
+        """
+        resp = await self._client.get(f"/s/{short_id}.json")
+        if resp.status_code == 404:
+            raise StoryNotFound(
+                story_id=short_id,
+                endpoint=resp.url,
+            )
+        resp.raise_for_status()
+        return Story.model_validate(resp.json())

lobstr-0.5.0/lobstr/services/tag.py

@@ -0,0 +1,46 @@
+from typing import List
+
+from lobstr.models import Tag, Tags
+from lobstr.exceptions import TagNotFound
+
+from .core import BaseService
+
+
+class TagService(BaseService):
+    """
+    Service for interacting with the tag endpoints of the Lobstr API.
+
+    Methods:
+        `get(name: str) -> Tag`: Retrieve a tag by its name.
+        `list() -> List[Tag]`: Retrieve a list of all available tags.
+    """
+
+    async def get(self, name: str) -> Tag:
+        """
+        Retrieve a tag by its name.
+
+        Args:
+            name (str): The name of the tag to retrieve.
+
+        Returns:
+            Tag: The tag object corresponding to the provided name.
+
+        Raises:
+            TagNotFound: If the tag with the specified name does not exist.
+        """
+        tags = await self.list()
+        for tag in tags:
+            if tag.name == name:
+                return tag
+        raise TagNotFound(name, endpoint=self._client.base_url)
+
+    async def list(self) -> List[Tag]:
+        """
+        Retrieve a list of all available tags.
+
+        Returns:
+            List[Tag]: A list of tag objects.
+        """
+        resp = await self._client.get("/tags.json")
+        resp.raise_for_status()
+        return Tags.validate_python(resp.json())

lobstr-0.5.0/lobstr/services/user.py

@@ -0,0 +1,33 @@
+from .core import BaseService
+
+from lobstr.models import User
+from lobstr.exceptions import UserNotFound
+
+
+class UserService(BaseService):
+    """
+    Service for interacting with the Lobstr API's user endpoints.
+
+    Methods:
+        `get(username: str) -> User`: Fetches user information by username.
+    """
+
+    async def get(self, username: str) -> User:
+        """
+        Fetches user information by username.
+
+        Args:
+            username (str): The username of the user to fetch.
+
+        Returns:
+            User: An instance of the User model containing user information.
+
+        Raises:
+            UserNotFound: If the user with the specified username does not exist.
+            HTTPError: If the request to the API fails for any other reason.
+        """
+        resp = await self._client.get(f"/~{username}.json")
+        if resp.status_code == 404:
+            raise UserNotFound(username, endpoint=self._client.base_url)
+        resp.raise_for_status()
+        return User.model_validate(resp.json())

lobstr-0.5.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+
+name = "lobstr"
+version = "0.5.0"
+description = "unofficial API client for lobste.rs"
+readme = "README.md"
+
+license = { text = "MIT" }
+authors = [{ name = "kavin", email = "kavin.srinivasan2@gmail.com" }]
+
+requires-python = ">=3.10"
+
+keywords = ["lobste.rs", "lobsters", "asyncio", "httpx", "pydantic"]
+
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "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",
+    "Topic :: Internet",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = ["httpx>=0.28.1", "pydantic>=2.13.4"]
+
+[project.urls]
+Homepage = "https://github.com/kavin81/lobstr"
+Repository = "https://github.com/kavin81/lobstr"
+Issues = "https://github.com/kavin81/lobstr/issues"
+
+[dependency-groups]
+
+dev = [
+    "isort>=8.0.1",
+    "ruff>=0.15.17",
+    "twine>=6.2.0",
+]
+
+docs = [
+    "mkdocs-shadcn>=0.10.7",
+    "mkdocstrings[python]>=1.0.4",
+    "properdocs>=1.6.7",
+    "pygments>=2.20.0",
+    "pymdown-extensions>=10.21.3",
+]
+
+[build-system]
+requires = ["uv-build>=0.8.15,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "lobstr"
+module-root = ""