Metadata-Version: 2.4
Name: hoyolab-rss-feeds
Version: 2.6.1
Summary: RSS feed generator for official game news from Hoyolab.
Author: c3kay
License-Expression: MIT
Project-URL: Repository, https://github.com/c3kay/hoyolab-rss-feeds
Keywords: hoyolab,rss,feed,rss-generator,jsonfeed,atom,genshin-impact,honkai-impact,honkai-starrail,zenless-zone-zero
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: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: News/Diary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp~=3.14.1
Requires-Dist: aiofiles~=25.1.0
Requires-Dist: pydantic<2,~=1.10.26
Requires-Dist: tomli~=2.4.1; python_version < "3.11"
Dynamic: license-file

# Hoyolab RSS Feeds

[![PyPI](https://img.shields.io/pypi/v/hoyolab-rss-feeds)](https://pypi.org/project/hoyolab-rss-feeds/)
[![Python Version](https://img.shields.io/pypi/pyversions/hoyolab-rss-feeds)](https://pypi.org/project/hoyolab-rss-feeds/)
[![Tests Status](https://img.shields.io/github/actions/workflow/status/c3kay/hoyolab-rss-feeds/build.yaml)](https://github.com/c3kay/hoyolab-rss-feeds/actions/workflows/build.yaml)
[![Codecov](https://codecov.io/gh/c3kay/hoyolab-rss-feeds/graph/badge.svg?token=Q8YYARNJ9P)](https://codecov.io/gh/c3kay/hoyolab-rss-feeds)

Generate RSS news feeds for Hoyoverse games like *Genshin Impact*, *Honkai Starrail*
or *Zenless Zone Zero* based on the official [Hoyolab](https://www.hoyolab.com) forum posts.
Available feed formats are [Atom](https://datatracker.ietf.org/doc/html/rfc4287)
and [JSON Feed](https://jsonfeed.org).
This application is supposed to run periodically by a cronjob for example.

## Installation

You can install the application from PyPI with:

```shell
python3 -m pip install hoyolab-rss-feeds
```

... or pull as Docker image:

```shell
docker pull ghcr.io/c3kay/hoyolab-rss-feeds
```

## Usage

### CLI

You can run the application like this:

```shell
hoyolabrssfeeds
```

... or explicitly as module:

```shell
python3 -m hoyolabrssfeeds
```

You can specify a custom path to the config file as parameter:

```shell
hoyolabrssfeeds -c path/to/config.toml
```

If no configuration can be found, a default config will be created
in your current directory (`./hoyolab-rss-feeds.toml`).

### Module

You can use the application as Python module/library and customize feed generation:

```python
from pathlib import Path
from hoyolabrssfeeds import FeedConfigLoader, GameFeed, GameFeedCollection, Game

async def generate_feeds():
    loader = FeedConfigLoader(Path("path/to/config.toml"))
    
    # option 1: all games found in config
    all_configs = await loader.get_all_feed_configs()
    feed_collection = GameFeedCollection.from_configs(all_configs)
    await feed_collection.create_feeds()
    
    # option 2: only a specific game from config
    genshin_config = await loader.get_feed_config(Game.GENSHIN)
    genshin_feed = GameFeed.from_config(genshin_config)
    await genshin_feed.create_feed()
```

[Here](https://gist.github.com/c3kay/2cd9833ef1c527e210aebf7a866336ed)
you can find an example on how to create a feed without using the config file.

### Docker

The application is also available as Docker image and can be run like this:

```shell
docker run \
  -v "/path/to/config.toml:/app/config.toml" \
  -v "/path/to/data:/data" \
  ghcr.io/c3kay/hoyolab-rss-feeds
```

The config file should be mounted to the default path `/app/config.toml`.
The `/data` directory should be used as the target directory for the generated
feeds and also need to be configured like so in the config file
(see option `feed.<format>.path` below).

**Note:** You still need some kind of scheduler like cron or Kubernetes
to run the image in a fixed interval to refresh the feeds!

## Configuration

In the TOML config file you can define the games you want to create feeds for
and in which format the feeds should be. Here is an example config:

```toml
language = "de-de"
category_size = 15

[genshin]
feed.json.path = "path/to/genshin.json"
feed.json.url = "https://example.org/genshin.json"
categories = ["Info", "Notices"]
category_size = 5
title = "Genshin Impact News"
icon = "https://example.org/icon.png"

[starrail]
feed.json.path = "path/to/starrail.json"
feed.json.url = "https://example.org/starrail.json"
feed.atom.path = "path/to/starrail.xml"
feed.atom.url = "https://example.org/starrail.xml"
```

A minimal configuration requires at least one game section with a `feed.<format>.path`
entry. Available feed formats are currently `json` and `atom`. You can either use
one format or both.

Entries defined at root level are considered default values and will apply to every
game section. The `feed` key can only be used in a game section. All other keys
can be defined at root level, and they can be overwritten by a game section.

The `categories` list defines the selected Hoyolab categories (*Info*, *Event* and
*Notices*) for this feed. If this entry is omitted, all categories are selected.
The `category_size` entry defines the amount of feed items (default: 5) of a category
for each feed. 

**Note:** When using Windows file paths (like `C:\\path\to\config.toml`), single quotes
should be used to avoid wrong auto-escaping of backslashes. More info about the TOML
format can be found in the [official documentation](https://toml.io/en/).

### Logging

Simple logs at level `INFO` are written to the terminal by default. If a file path is given
via parameter (`-l /path/to/out.log`), the logs are written to this file.

If the application is used as module, the logger must be 
[configured](https://docs.python.org/3.11/howto/logging.html#configuring-logging) separately. 
The application specific logger is available by:

```python
import logging
logger = logging.getLogger("hoyolabrssfeeds")
```

### Options

#### Games

| Game                | Section    |
|---------------------|------------|
| Genshin Impact      | `genshin`  |
| Honkai Impact 3rd   | `honkai`   |
| Honkai: Starrail    | `starrail` |
| Zenless Zone Zero   | `zenless`  |
| Tears of Themis     | `themis`   |
| Honkai: Nexus Anima | `nexus`    |
| Petit Planet        | `planet`   |

#### Languages

*English is the default language.*

| Language     | Code    |
|--------------|---------|
| German       | `de-de` |
| English      | `en-us` |
| Spanish      | `es-es` |
| French       | `fr-fr` |
| Indonesian   | `id-id` |
| Italian      | `it-it` |
| Japanese     | `ja-jp` |
| Korean       | `ko-kr` |
| Portuguese   | `pt-pt` |
| Russian      | `ru-ru` |
| Thai         | `th-th` |
| Turkish      | `tr-tr` |
| Vietnamese   | `vi-vn` |
| Chinese (CN) | `zh-cn` |
| Chinese (TW) | `zh-tw` |
