https://github.com/ugns/rss2socials
Modular Python CLI tool to automatically post new entries from an RSS or Atom feed to one or more social media platforms. Easily extensible, robust, and safe for automation and CI/CD workflows.
https://github.com/ugns/rss2socials
atom-feed bluesky generative-ai python3 rss-parser social-media
Last synced: 6 months ago
JSON representation
Modular Python CLI tool to automatically post new entries from an RSS or Atom feed to one or more social media platforms. Easily extensible, robust, and safe for automation and CI/CD workflows.
- Host: GitHub
- URL: https://github.com/ugns/rss2socials
- Owner: ugns
- License: mit
- Created: 2025-06-26T02:10:02.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-07-08T21:21:53.000Z (6 months ago)
- Last Synced: 2025-07-08T22:26:42.049Z (6 months ago)
- Topics: atom-feed, bluesky, generative-ai, python3, rss-parser, social-media
- Language: Python
- Homepage:
- Size: 44.9 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# rss2socials
[](https://pypi.org/project/rss2socials/)
[](https://pypi.org/project/rss2socials/)
[](https://github.com/ugns/rss2socials/actions/workflows/ci.yml)
[](https://codecov.io/gh/ugns/rss2socials)
[](https://github.com/ugns/rss2socials/blob/main/LICENSE)
[](https://pypistats.org/packages/rss2socials)
**rss2socials** is a modular Python CLI tool that automatically posts new entries from an RSS or Atom feed to one or more social media platforms. It is designed to be easily extensible, robust, and safe for automation and CI/CD workflows.
## Features
- **Dynamic connector system:** Add new social media platforms by simply dropping a connector module in `src/rss2socials/connector/`.
- **Automatic deduplication:** Tracks posted links to avoid reposting.
- **OpenAI-powered summaries:** Generates concise, platform-appropriate summaries for each post.
- **Flexible CLI:** Configure via command-line arguments or environment variables.
- **Comprehensive logging:** Supports configurable log levels for debugging and automation.
- **Tested and maintainable:** 100% test coverage for core modules, with robust error handling.
## Installation
### From PyPI
```sh
pip install rss2socials
```
### From Source (Recommended for Development)
Clone the repository and install all dependencies (main + dev) using pip-tools and a pinned requirements file for reproducibility:
```sh
git clone https://github.com/ugns/rss2socials.git
cd rss2socials
pip install pip-tools
pip-compile --extra dev --strip-extras --output-file=requirements.txt pyproject.toml
pip install -r requirements.txt
```
- This will install the package in editable mode along with all development tools (pytest, flake8, etc.).
- You can also use `make dev` to automate these steps.
## Requirements
- **Python 3.9 or newer is required.**
## Usage
### Using the CLI Entrypoint
After installation, you can use the CLI entrypoint (if installed from PyPI or with pip):
```sh
rss2socials --feed-url https://example.com/feed.xml --platform bluesky
```
Or, if you prefer to use the Python module directly:
```sh
python -m rss2socials --feed-url https://example.com/feed.xml --platform bluesky
```
Both commands are equivalent and will invoke the CLI interface.
### As a Library
You can also use `rss2socials` as a Python library in your own scripts:
```python
from rss2socials.cli import main
# Call main() with sys.argv-style arguments
main([
"--feed-url", "https://example.com/feed.xml",
"--platform", "bluesky"
])
```
### CLI Options
- `--feed-url` (or `FEED_URL` env): RSS/Atom feed URL (required)
- `--platform`: One or more platforms to post to (default: bluesky; auto-discovers available platforms)
- `--seen-file`: File to track posted links (default: `seen_rss_posts.txt`)
- `--post-age-limit-days`: Only post entries newer than this many days (default: 7)
- `--log-level`: Logging level (default: INFO)
## Dynamic Connector System
To add support for a new social media platform:
1. Create a new Python file in `src/rss2socials/connector/` (e.g., `myplatform.py`).
2. Implement a `post(summary, link, fetch_page_metadata)` function and set a `PLATFORM` string (e.g., `PLATFORM = "myplatform"`).
3. Optionally, set `MAX_GRAPHEMES` for platform-specific length limits.
The CLI will automatically discover and make your platform available as a `--platform` option. No changes to the core code are required.
**Example connector skeleton:**
```python
PLATFORM = "myplatform"
MAX_GRAPHEMES = 300
def post(summary, link, fetch_page_metadata):
# Implement posting logic here
return True # Return True if successful
```
## Environment Variables
- `OPENAI_API_KEY`: Required for summary generation
- `FEED_URL`, `SEEN_FILE`, `POST_AGE_LIMIT_DAYS`, `LOG_LEVEL`, `PLATFORM`: Optional, override CLI args
- **Connector-specific variables:**
- For Bluesky:
- `BLUESKY_HANDLE`: Your Bluesky username (required)
- `BLUESKY_APP_PASSWORD`: Your Bluesky app password (required)
- Other connectors may require their own environment variables; see the connector's documentation or source code for details.
## Development & Testing
- Install all dependencies: `make dev`
- Run tests: `make test` (uses tox for all supported Python versions)
- Lint: `make lint`
- Coverage: `make coverage`
- Add new connectors in `src/rss2socials/connector/`
- Regenerate constraints after dependency changes: `make freeze`
## License
MIT
## Contributing
Contributions are welcome! Please use [Conventional Commits](https://www.conventionalcommits.org/) and ensure all tests pass before submitting a PR.