{"id":28087541,"url":"https://github.com/thiswillbeyourgithub/freshrss_python_api","last_synced_at":"2025-08-02T08:04:20.710Z","repository":{"id":280439520,"uuid":"942009611","full_name":"thiswillbeyourgithub/freshrss_python_api","owner":"thiswillbeyourgithub","description":"A Python client for interacting with the FreshRSS Fever API, providing easy access to feeds, items, and management features.","archived":false,"fork":false,"pushed_at":"2025-06-04T20:47:26.000Z","size":80,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-10T19:43:38.163Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thiswillbeyourgithub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-03T12:29:15.000Z","updated_at":"2025-07-08T08:26:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"a3258c3e-91f3-4c06-9f74-9331829a9db1","html_url":"https://github.com/thiswillbeyourgithub/freshrss_python_api","commit_stats":null,"previous_names":["thiswillbeyourgithub/freshrss_python_api"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/thiswillbeyourgithub/freshrss_python_api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiswillbeyourgithub%2Ffreshrss_python_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiswillbeyourgithub%2Ffreshrss_python_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiswillbeyourgithub%2Ffreshrss_python_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiswillbeyourgithub%2Ffreshrss_python_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thiswillbeyourgithub","download_url":"https://codeload.github.com/thiswillbeyourgithub/freshrss_python_api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiswillbeyourgithub%2Ffreshrss_python_api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268351024,"owners_count":24236329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-13T11:32:09.716Z","updated_at":"2025-08-02T08:04:20.701Z","avatar_url":"https://github.com/thiswillbeyourgithub.png","language":"Python","readme":"# FreshRSS Python API Client\n\n[![PyPI Version](https://img.shields.io/pypi/v/freshrss-api)](https://pypi.org/project/freshrss-api/)\n[![License](https://img.shields.io/badge/license-GPLv3-blue)](LICENSE)\n\nA Python client for interacting with the FreshRSS Fever API. This library provides an easy-to-use interface for fetching items, marking items as read/saved/unsaved, and managing feeds and categories in your FreshRSS instance.\n\n## Features\n\n- **Authentication**: Securely authenticate with your FreshRSS instance using your username and API password or environment variables.\n- **Item Management**: Fetch unread items, saved items, or items by ID or date range. Mark items as read, saved, or unsaved.\n- **Feeds \u0026 Groups**: Retrieve all feeds and groups (categories) from your FreshRSS instance.\n- **Date-based Queries**: Fetch items between specific dates with the `get_items_from_dates()` method.\n- **Robust Error Handling**: Automatic retries for API requests with detailed error reporting.\n- **Type Safety**: Optional type checking with `beartype` for improved code reliability.\n- **Environment Variables**: Configure the client using environment variables for easier integration with CI/CD pipelines and containerized environments.\n- **Verbose Logging**: Optional detailed logging of API requests and responses using Loguru.\n\n## Related Projects\n\nThe author of this library also created [freshrss_to_karakeep](https://github.com/thiswillbeyourgithub/freshrss_to_karakeep), a Python script to periodically send FreshRSS \"favourite\" items to [Karakeep](https://github.com/karakeep-app/karakeep) (a bookmarking and read-it-later app).\n\n## Installation\n\nYou can install the FreshRSS API client via pip:\n\n```bash\npip install freshrss-api\n```\n\n## Usage\n\n### Environment Variables\n\nThe FreshRSS API client supports the following environment variables:\n\n- `FRESHRSS_PYTHON_API_HOST`: Your FreshRSS instance URL (e.g., \"https://freshrss.example.net\")\n- `FRESHRSS_PYTHON_API_USERNAME`: Your FreshRSS username\n- `FRESHRSS_PYTHON_API_PASSWORD`: Your FreshRSS API password\n- `FRESHRSS_PYTHON_API_VERIFY_SSL`: Whether to verify SSL certificates (\"true\", \"1\", \"yes\" for True, anything else for False)\n\nThese environment variables can be used instead of passing parameters directly to the constructor.\n\n### Initialization\n\nTo start using the FreshRSS API client, initialize it with your FreshRSS instance URL, username, and API password.\n\n```python\nfrom freshrss_api import FreshRSSAPI\n\n# Initialize the client with direct parameters\nclient = FreshRSSAPI(\n    host=\"https://freshrss.example.net\",\n    username=\"your_username\",\n    password=\"your_api_password\",\n    verify_ssl=True,\n    verbose=False\n)\n\n# Or use environment variables\n# export FRESHRSS_PYTHON_API_HOST=\"https://freshrss.example.net\"\n# export FRESHRSS_PYTHON_API_USERNAME=\"your_username\"\n# export FRESHRSS_PYTHON_API_PASSWORD=\"your_api_password\"\n# export FRESHRSS_PYTHON_API_VERIFY_SSL=\"true\"\nclient = FreshRSSAPI()  # Will use environment variables\n```\n\n### Fetching Items\n\nYou can fetch unread items, saved items, or items by specific IDs or date ranges:\n\n```python\n# Fetch unread items\nunread_items = client.get_unreads()\n\n# Fetch saved items\nsaved_items = client.get_saved()\n\n# Fetch items by IDs\nitems = client.get_items_from_ids([12345, 67890])\n\n# Fetch items between dates\nitems = client.get_items_from_dates(\n    since=\"2023-01-01\",  # Can be string, datetime, or timestamp\n    until=\"2023-01-31\",  # Optional, defaults to current time\n    date_format=\"%Y-%m-%d\"  # Optional format string for date parsing\n)\n```\n\n### Marking Items\n\nMark items as read, saved, or unsaved using the `set_mark` method:\n\n```python\n# Mark an item as read\nclient.set_mark(as_=\"read\", id=12345)\n\n# Mark an item as saved (starred)\nclient.set_mark(as_=\"saved\", id=12345)\n\n# Mark an item as unsaved (unstarred)\nclient.set_mark(as_=\"unsaved\", id=12345)\n```\n\nNote: The Fever API does not support marking items as unread.\n\n### Managing Feeds and Groups\n\nFetch all feeds or groups (categories) from your FreshRSS instance:\n\n```python\n# Get all feeds\nfeeds = client.get_feeds()\n\n# Get all groups (categories)\ngroups = client.get_groups()\n```\n\n### Working with Dates and IDs\n\nIn the FreshRSS API, item IDs are timestamps in microseconds. The library provides a helper method to convert dates to IDs:\n\n```python\n# Convert a date string to an ID\nid = FreshRSSAPI._date_to_id(\"2023-01-15\")  # Static method\n\n# Item objects have datetime properties\nfor item in items:\n    print(f\"Item created on: {item.created_datetime}\")\n    print(f\"Item ID as datetime: {item.id_datetime}\")\n```\n\n### Verbose Logging\n\nEnable verbose logging to see detailed information about API requests and responses:\n\n```python\nclient = FreshRSSAPI(verbose=True)\n# Now all API calls will log detailed information using Loguru\n```\n\n## API Details\n\nThis library interacts with the FreshRSS Fever API, which is a simplified API for mobile access and third-party integrations. The API endpoints are well-documented and provide access to most features of FreshRSS.\n\nFor more details on the Fever API, refer to the [official documentation](https://freshrss.github.io/FreshRSS/en/developers/06_Fever_API.html), as well as this [internet archive page](https://web.archive.org/web/20230616124016/feedafever.com/api).\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 (GPLv3). See the [LICENSE](LICENSE) file for more details.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request if you have any improvements or bug fixes.\n\n## Acknowledgements\n\nThis project was inspired by the need for a simple and reliable Python client for the FreshRSS Fever API. Thanks to the FreshRSS team for their work on this excellent RSS aggregator!\n\n## Contact\n\nFor any questions or issues, please open an issue here.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthiswillbeyourgithub%2Ffreshrss_python_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthiswillbeyourgithub%2Ffreshrss_python_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthiswillbeyourgithub%2Ffreshrss_python_api/lists"}