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)