| Name | smslib JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | |
| Summary | Python library for sending SMS messages via email-to-SMS gateways |
| upload_time | 2023-03-23 18:43:27 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2023 Nathaniel D. Hoffman Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
sms
text messages
email-to-sms gateway
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# smslib
### A *very simple* library for sending *very simple* text messages via SMS-to-email gateways
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.
## Installation
This package is available via PyPI:
```sh
$ pip install smslib
```
Alternatively, clone the repo and install it manually:
```sh
$ git clone git@github.com:denehoffman/smslib.git
$ cd smslib
$ pip install .
```
## Usage
### In a python script
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:
```python
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](https://support.google.com/accounts/answer/185833?hl=en). If everything works correctly, you should get a text message that says `"Hello world"`! The package uses `smtplib`'s [`SMTP.send_message`](https://docs.python.org/3/library/smtplib.html#smtplib.SMTP.send_message) function (under [TLS encryption](https://docs.python.org/3/library/smtplib.html#smtplib.SMTP.starttls)), so feel free to use an [`email.message.Message`](https://docs.python.org/3/library/email.compat32-message.html#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`:
```python
receiver = smslib.Receiver(None, None, email="my.friends.email@university.edu")
```
You can also specify an [ssl.SSLContext](https://docs.python.org/3/library/ssl.html#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.
### In a shell script
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.
```sh
$ 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 message
```
This 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:
```toml
# ~/.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
```sh
$ notify "Hello world!" --sender myself --receiver myfriend
```
This 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
```sh
$ notify "Hello world!" --sender myself --receiver myfriend --port 123
```
will 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`](https://docs.python.org/3/library/getpass.html) 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.
## Changelog
- v1.0.0
- Initial commit with base functionality
## Planned Features
None so far, but I'm sure I'll think of a few things. If anyone reading this has suggestions, let me know!
Raw data
{
"_id": null,
"home_page": "",
"name": "smslib",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "SMS,text messages,email-to-SMS gateway",
"author": "",
"author_email": "Nathaniel Dene Hoffman <dene@cmu.edu>",
"download_url": "https://files.pythonhosted.org/packages/25/34/3b372a78952b58069b1b960d5815dbc39243e86fa9e5fa20e46e2d3d745c/smslib-1.0.0.tar.gz",
"platform": null,
"description": "# smslib\n### A *very simple* library for sending *very simple* text messages via SMS-to-email gateways\n\nI 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.\n\n## Installation\nThis package is available via PyPI:\n```sh\n$ pip install smslib\n```\nAlternatively, clone the repo and install it manually:\n```sh\n$ git clone git@github.com:denehoffman/smslib.git\n$ cd smslib\n$ pip install .\n```\n\n## Usage\n### In a python script\nThere 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:\n```python\nimport smslib\nsender = smslib.Sender(\"my_email@gmail.com\", \"mypassword\", \"smtp.gmail.com\")\nreceiver = smslib.Receiver(\"123-456-7890\", \"at&t\")\nsender.send_message(\"Hello world!\", receiver)\n```\nThat'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](https://support.google.com/accounts/answer/185833?hl=en). If everything works correctly, you should get a text message that says `\"Hello world\"`! The package uses `smtplib`'s [`SMTP.send_message`](https://docs.python.org/3/library/smtplib.html#smtplib.SMTP.send_message) function (under [TLS encryption](https://docs.python.org/3/library/smtplib.html#smtplib.SMTP.starttls)), so feel free to use an [`email.message.Message`](https://docs.python.org/3/library/email.compat32-message.html#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`:\n```python\nreceiver = smslib.Receiver(None, None, email=\"my.friends.email@university.edu\")\n```\nYou can also specify an [ssl.SSLContext](https://docs.python.org/3/library/ssl.html#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.\n\n### In a shell script\nThe 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.\n```sh\n$ notify --help\nusage: notify [-h] [--sender SENDER] [--receiver RECEIVER] [--email EMAIL] [--password PASSWORD]\n [--smtp-server SMTP_SERVER] [--port PORT] [--phone-number PHONE_NUMBER]\n [--provider PROVIDER] [--confirm]\n message\n\nSend an SMS via email Available SMS providers: verizon, at&t, att, tmobile, sprint, boost\n\npositional arguments:\n message Message string to send\n\noptional arguments:\n -h, --help show this help message and exit\n --sender SENDER Sender name from ~/.smslibrc.toml\n --receiver RECEIVER Receiver name from ~/.smslibrc.toml\n --email EMAIL Sender's email address\n --password PASSWORD Sender's password\n --smtp-server SMTP_SERVER\n Sender's SMTP server\n --port PORT Sender's SMTP server port\n --phone-number PHONE_NUMBER\n Receiver's phone number\n --provider PROVIDER Receiver's phone provider\n --confirm Print confirmation after sending message\n```\nThis 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:\n```toml\n# ~/.smslibrc.toml\n\n[senders]\n[senders.myself]\nemail = \"my.email@gmail.com\"\npassword = \"mypassword\"\nsmtp_server = \"smtp.gmail.com\"\nport = 587\n\n[receivers]\n[receivers.myfriend]\nphone_number = \"123-456-7890\"\nprovider = \"att\"\n```\nThen we can just call the `notify` command as\n```sh\n$ notify \"Hello world!\" --sender myself --receiver myfriend\n```\nThis 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\n```sh\n$ notify \"Hello world!\" --sender myself --receiver myfriend --port 123\n```\nwill 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.\n\nFinally, 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`](https://docs.python.org/3/library/getpass.html) 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.\n\n## Changelog\n- v1.0.0\n - Initial commit with base functionality\n\n## Planned Features\nNone so far, but I'm sure I'll think of a few things. If anyone reading this has suggestions, let me know!\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 Nathaniel D. Hoffman Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Python library for sending SMS messages via email-to-SMS gateways",
"version": "1.0.0",
"split_keywords": [
"sms",
"text messages",
"email-to-sms gateway"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "02a7571bdc9ca7f1b340d54656c64e342197402392de67873086795a9baec58b",
"md5": "0c5571f8b63e9bf3c21c6be239df8f8e",
"sha256": "00bbefafebf03b55467872c844186cec7ae8145d1b29adcda4c25c5fef733d3f"
},
"downloads": -1,
"filename": "smslib-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c5571f8b63e9bf3c21c6be239df8f8e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8731,
"upload_time": "2023-03-23T18:43:25",
"upload_time_iso_8601": "2023-03-23T18:43:25.662995Z",
"url": "https://files.pythonhosted.org/packages/02/a7/571bdc9ca7f1b340d54656c64e342197402392de67873086795a9baec58b/smslib-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "25343b372a78952b58069b1b960d5815dbc39243e86fa9e5fa20e46e2d3d745c",
"md5": "35246ef4c0a46919cc9105f99151fa57",
"sha256": "90b9b529caa0e64a314b6a62b43ddcb930996c4a7502aed421898a3a22e9b453"
},
"downloads": -1,
"filename": "smslib-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "35246ef4c0a46919cc9105f99151fa57",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10450,
"upload_time": "2023-03-23T18:43:27",
"upload_time_iso_8601": "2023-03-23T18:43:27.767344Z",
"url": "https://files.pythonhosted.org/packages/25/34/3b372a78952b58069b1b960d5815dbc39243e86fa9e5fa20e46e2d3d745c/smslib-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-23 18:43:27",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "smslib"
}
