{"id":15539558,"url":"https://github.com/scarlehoff/pybliotecario","last_synced_at":"2025-04-23T16:10:55.468Z","repository":{"id":35067089,"uuid":"163082971","full_name":"scarlehoff/pybliotecario","owner":"scarlehoff","description":"Personal bot to interact from your computer with telegram or facebook messenger with a focus on extensibility in the form of small modules","archived":false,"fork":false,"pushed_at":"2024-07-24T05:39:24.000Z","size":290,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-09T12:54:52.725Z","etag":null,"topics":["arxiv","dice","facebook","github","python","telegram","telegram-bot","wikipedia"],"latest_commit_sha":null,"homepage":"","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/scarlehoff.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","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}},"created_at":"2018-12-25T12:58:15.000Z","updated_at":"2024-07-12T22:03:11.000Z","dependencies_parsed_at":"2023-02-12T21:15:13.587Z","dependency_job_id":"d752e7c0-9275-461b-a573-61474ada7108","html_url":"https://github.com/scarlehoff/pybliotecario","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scarlehoff%2Fpybliotecario","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scarlehoff%2Fpybliotecario/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scarlehoff%2Fpybliotecario/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scarlehoff%2Fpybliotecario/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scarlehoff","download_url":"https://codeload.github.com/scarlehoff/pybliotecario/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250468270,"owners_count":21435452,"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","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":["arxiv","dice","facebook","github","python","telegram","telegram-bot","wikipedia"],"created_at":"2024-10-02T12:10:43.839Z","updated_at":"2025-04-23T16:10:55.444Z","avatar_url":"https://github.com/scarlehoff.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI version](https://badge.fury.io/py/pybliotecario.svg)](https://badge.fury.io/py/pybliotecario)\n![Tests](https://github.com/scarlehoff/pybliotecario/workflows/pytest/badge.svg)\n\n# pybliotecario\n\npybliotecario is a simple messaging bot written in python.\n\nThe goal of the program is to be as extensible as possible, both from the point of view of the possibilities it can offer\n(in the form of [components](https://github.com/scarlehoff/pybliotecario/tree/master/src/pybliotecario/components)) and\nthe backends it can support, which right now includes [Telegram and Facebook](https://github.com/scarlehoff/pybliotecario/tree/master/src/pybliotecario/backend)\n\nWith this program one can effortlessly maintain an active connection between the computer in which it runs and your phone!\n\n## Installing the pybliotecario\n\nThe pybliotecario program is in [pip](https://pypi.org/project/pybliotecario/)\nand the base program can be installed with:\n\n```bash\npip install pybliotecario\n```\n\nIf you want to install all dependencies for [all components](https://github.com/scarlehoff/pybliotecario/blob/master/pyproject.toml#L30) do\n\n```bash\npip install pybliotecario[full]\n```\n\nYou can also install it using the development version:\n\n```bash\ngit clone https://github.com/scarlehoff/pybliotecario.git\ncd pybliotecario\npython3 -m pip install .\n```\n\nA small `systemd_install.sh` script is included in the repository in order to easily daemonize it.\n\n## How to connect the pybliotecario to Telegram\nThe main backend for the pybliotecario is Telegram, although facebook can also be used (see [here](https://github.com/scarlehoff/pybliotecario/tree/master/src/pybliotecario/backend))\nIn order to communicate with Telegram is necessary to request an API by talking with Telegram's BotFather bot.\nThe `--init` option will guide you through the process.\n\n```\npybliotecario --init\n```\n\nRemember that if you installed the development version you will need to use instead the name of your computer as executable!\n\n## Configuration of the pybliotecario\n\nAll configuration options for the pybliotecario can be found in the `${XDG_CONFIG_HOME}/pybliotecario/pybliotecario.ini` file.\nIn most systems this resolves to `~/.config/pybliotecario/pybliotecario.ini`.\nThis file is automatically created (and most of the options filled) by running `--init`\nand its syntax follows that of the python default [ConfigParser](https://docs.python.org/3/library/configparser.html).\n\n## Basic usage\n\nOnce `--init`` has been run for the first time (and thus the API key is in found in `pybliotecario.ini`)\nit is possible to start using the program.\nTo send a message to your Telegram account run:\n\n```\npybliotecario \"Hello world!\"\n```\n\nInstead, to start receiving messages from your phone you can run with:\n\n```\npybliotecario -d --debug\n```\n\nUse the `--debug` flag if you want to see a verbose output of what's happening!\n\n\n## Extending the pybliotecario \n\nThe program aims to be 100% extensible, running any kind of action in two different modes:\n\n- Command line: just call the command with the proper arguments. For instance, send a msg to your phone.\n- Message command: write a command to the bot from telegram, so the bot can act on said command.\n\nAdding new actions to each of the different modes is trivial, there are a small example for each case in the relevant files.\n\nIn order to add a new command to the bot you need to modify the file `on_cmdline.py` (for command line arguments) or `on_cmd_message.py` for commands sent from Telegram. \nThe easiest course of action is to copy one of the components (in the `components` folder you can see the different modules) and add your own actions.\nThe simplest of them is probably `components/ip_lookup.py` so have a look at it!\n\n\n\n## Message command:\n\nThese are command received by the bot in the form `/command Do whatever`. In the file `on_cmd_message.py` just add a new command to the if condition. The command definition will be defined in the variable `tg_command`.\n\nThere you can just write the python code to perform the command or add a new component. All the information from the msg the bot just received will be included in the `message_obj` variable. In particular the text will be `message_obj.text`.\n\nExample: if you send the command /ip, the bot will respond with the current ip of the machine it is running in.\n\n### help command\n\nYou can ask the pybliotecario at any point to send you a list of the available commands with the msg `/help`:\n\n```\n\u003e PID module\n    /kill_pid pid: kills a given pid\n    /is_pid_alive pid/name_of_program: looks for the given pid or program to check whether it is still alive\n \u003e IP module\n    /ip : send the current ip in which the bot is running \n \u003e Arxiv module\n    /arxiv arxiv_id: sends information about the given id\n    /arxiv_get arxiv_id: sends the PDF for the given id \n \u003e Script module\n    /script list: list all possible scripts\n    /script script_name: execute the given script \n \u003e DnD module\n    /r, /roll dice [text]: roll a dice in the format NdM+Mod\n \u003e Reactions module\n    /reaction_save reaction_name: save an image with name reaction_name\n    /reaction_list: list all reactions\n    /reaction reaction_name: sends the reaction given by reaction_name \n \u003e Wikipedia module\n    /wiki term: search for term in wikipedia, return the summary\n    /wiki_full N term: read the full article and return N times the defined summary_size\n \u003e System component\n    /system uptime: returns the uptime of the computer in which the bot lives\n \u003e Stocks component\n    /stock_price ticker: returns the current price for the given ticker\n \u003e Twitter component:\n    /twitter_tl [@user] [N=20]: send the last N tweets from the TL [of user @user]\n    /twitter_mentions [N=5]: send the last N mentions\n    /twitter_tweet \u003ctext\u003e: send a tweet\n\n```\n\n\n## Command line:\n\nIn the file `on_cmdline.py` add a new if condition. You can add your action there as python code. If you want to do something more complicated I suggest you create a new component (pull requests are welcome!)\n\nNote: if you need new command line arguments (you surely do!) don't forget to add them to the end of `argument_parser.py`!\n\nExample: \n```\npybliotecario -i test.jpg\n```\n\nthis will send the image named `test.img` to your defined Telegram chat\n\n### Available cmd_line options:\n\n- msg: sends msg to Telegram\n- -i: sends an image to Telegram (or other backend)\n- -f: sends a file to Telegram (or other backend)\n- --chat_id: target a specific chat ID (e.g.: `~$ pybliotecario \"test\" --chat_id 12312` will send the msg \"test\" to 12312 instead of the`chat_id` defined in the `.ini` file).\n- --arxiv_new: sends a msg to Telegram with the latest submissions to arxiv, filtered as you see fit (uses https://github.com/lukasschwab/arxiv.py as API)\n- --weather: sends a msg to Telegram with the current weather and some information about the forecast (uses https://github.com/csparpa/pyowm as OpenWeatherMap API, which needs an API key)\n- --check_repository: sends a msg to Telegram with the incoming changes to the repository\n- --my_ip: send the ip of the bot to the defined telegram user\n- --pid: Monitor a process by PID, run all other options after the process has finished.\n- --stock_watcher json.file: check information about stocks according to the definitions defined in the component [file](https://github.com/scarlehoff/pybliotecario/blob/master/src/pybliotecario/components/stocks.py)\n\n## Some examples and ideas:\nFor instance, you can run the pybliotecario every morning at 7:15 a.m. to tell you what are the news in the arxiv today adding a cronjob:\n\n    15 07 * * mon-fri /home/pi/Telegram/pybliotecario/pybliotecario.py --arxiv_new\n\n## Contributing\nIf you have any new ideas for enhancements or have noticed any bugs, feel free to open an issue or a Pull Request :)\nThis is a toy-project I am maintaining, but I will do my best to help.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscarlehoff%2Fpybliotecario","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscarlehoff%2Fpybliotecario","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscarlehoff%2Fpybliotecario/lists"}