I often run code on a remote computer cluster, and sometimes this code takes a very long time to run. This project was inspired by a desire to receive a notification on my phone when my programs wrap up, without using a fancy API, installing a third-party messaging program, and (most importantly) paying money. After all, I already pay to send and recieve texts, and email is free these days. Most common US phone providers have a way to send texts via an email. For example, if your phone number is +1-(123)-456-7890, and your service provider is AT&T, you can, right now, send yourself a text message by emailing 1234567890@txt.att.net. This is the core idea behind the library.
This package is available via PyPI:
$ pip install smslibAlternatively, clone the repo and install it manually:
$ git clone git@github.com:denehoffman/smslib.git
$ cd smslib
$ pip install .There are several ways to use the package. It contains three submodules, sender, receiver, and notify. To manually use the library inside python, ignore the notify submodule and write something like the following:
import smslib
sender = smslib.Sender("my_email@gmail.com", "mypassword", "smtp.gmail.com")
receiver = smslib.Receiver("123-456-7890", "at&t")
sender.send_message("Hello world!", receiver)That's pretty much all of the core functionality. Note that for GMail, if you have 2FA turned on, you might need to create an app password. If everything works correctly, you should get a text message that says "Hello world"! The package uses smtplib's SMTP.send_message function (under TLS encryption), so feel free to use an email.message.Message object instead of a string. There is also the option to send a regular email instead of a text (or maybe it's a text to a phone provider that isn't in the default list) by specifying an email address in to the Receiver:
receiver = smslib.Receiver(None, None, email="my.friends.email@university.edu")You can also specify an ssl.SSLContext using a context keyword argument in send_message. Additionally, a port can be specified using the port keyword argument in smslib.Sender, although the default, 587, should be sufficient for most use cases.
The other way to use the library is through a simple command-line interface. This gets built automatically when installed, and the command is called notify. I realize this has the potential to conflict with some other programs, which is why I would advise the use of a virtual python environment.
$ notify --help
usage: notify [-h] [--sender SENDER] [--receiver RECEIVER] [--email EMAIL] [--password PASSWORD]
[--smtp-server SMTP_SERVER] [--port PORT] [--phone-number PHONE_NUMBER]
[--provider PROVIDER] [--confirm]
message
Send an SMS via email Available SMS providers: verizon, at&t, att, tmobile, sprint, boost
positional arguments:
message Message string to send
optional arguments:
-h, --help show this help message and exit
--sender SENDER Sender name from ~/.smslibrc.toml
--receiver RECEIVER Receiver name from ~/.smslibrc.toml
--email EMAIL Sender's email address
--password PASSWORD Sender's password
--smtp-server SMTP_SERVER
Sender's SMTP server
--port PORT Sender's SMTP server port
--phone-number PHONE_NUMBER
Receiver's phone number
--provider PROVIDER Receiver's phone provider
--confirm Print confirmation after sending messageThis contains all of the fields above (note that --port is completely optional and has a default value of 587) with two additional arguments, --sender and --receiver. I set this up to cut down on the hastle of entering in all the information in a long shell command every time. By default, it will look for a TOML file located in your home directory. An example is as follows:
# ~/.smslibrc.toml
[senders]
[senders.myself]
email = "my.email@gmail.com"
password = "mypassword"
smtp_server = "smtp.gmail.com"
port = 587
[receivers]
[receivers.myfriend]
phone_number = "123-456-7890"
provider = "att"Then we can just call the notify command as
$ notify "Hello world!" --sender myself --receiver myfriendThis file can be located anywhere, and the default location can be overwritten by setting the $SMSLIBRC environment variable to point to the desired path. Any command-line arguments here will have precedence over the .smslibrc.toml file. For example
$ notify "Hello world!" --sender myself --receiver myfriend --port 123will send the message over port 123 rather than the 587 specified in the file. Furthermore, while there was an option to send a message to any custom email address via the email keyword in smslib.Receiver, there is no command-line option for this. However, adding an email field to the corresponding reciever in .smslibrc.toml will give you this functionality in the shell.
Finally, any fields which are not specified explicitly will be acquired by prompting the user in shell. All of these are raw input fields, with the exception of the sender's password, which uses getpass to hide the password input. It is usually not the best practice to store your passwords in code or in a configuration file, but I allow this as an option because GMail's "app passwords" are randomly generated strings which are not easy to type or remember.
- v1.0.0
- Initial commit with base functionality
None so far, but I'm sure I'll think of a few things. If anyone reading this has suggestions, let me know!