Python library that allows to send messages using Plusserver SMS platform.
Project description
sms_plusserver
==============
Python library that allows to send messages using Plusserver SMS platform.
Installation
------------
```
pip install sms_plusserver
```
Usage
-----
In order to use this library users need to have an account on
Plusserver SMS platform (https://sms.openit.de/).
#### Quick start
`sms_plusserver` provides module-level convenience functions to make sending
messages easier:
```python
from sms_plusserver import configure, send_sms
# Configure service:
configure(username='user', password='pass')
# Send a message:
send_sms('+4911122233344', 'Hello!')
```
#### Configuration
`configure` function allows to set all configuration options. These options
will be used by other functions / classes of the module by default.
```python
from sms_plusserver import configure
configure(
# Your Plusserver credentials (required):
username='user',
password='pass',
# Optional parameters:
project='MyAppNotifications', # Name of your app / project
orig='MyApp', # SMS origin (name or phone number)
timeout=60 # Default timeout for service API calls
)
```
#### Sending messages
The easiest way to send a message is to call `send_sms` function:
```python
>>> from sms_plusserver import send_sms
>>> send_sms('+4911122233344', 'Hello!')
'a1d0c6e83f027327d8461063f4ac58a6' # Handle ID - unique message identifier
```
User can provide sender name or number in `orig` parameter:
```python
send_sms('+4911122233344', 'Hello!', orig='+4955544433300')
```
Messages on Plusserver platform can be tagged using `project` param:
```python
send_sms('+4911122233344', 'Hello!', project='MyProject')
```
By default all messages receive unique identifiers - "Handle ID".
This identifier allows user to check message status.
To send unregistered message user can set `registered_delivery` parameter
to `False`:
```python
>>> from sms_plusserver import send_sms
>>> send_sms('+4911122233344', 'Hello!', registered_delivery=False)
True # No "Handle ID", just True (message sent) or False (error)
```
In order to test SMS service without sending actual message, user can set
`debug` parameter to `True`. Debug messages will not receive "Handle ID":
```python
send_sms('+4911122233344', 'Hello!', debug=True)
```
All API calls are made using HTTP requests to Plusserver web API. User can
specify network timeout for each request:
```python
send_sms('+4911122233344', 'Hello!', timeout=30)
```
To silence exceptions raised due to network errors or errors returned from
provider's API, user can set `fail_silently` parameter to `True`:
```python
send_sms('+4911122233344', 'Hello!', fail_silently=True)
```
In this case, `send_sms` function will return `None` when error occurs.
#### Checking state of a message
To check status of a message with given "Handle ID" user can call
`check_sms_state` function:
```python
>>> from sms_plusserver import check_sms_state
>>> check_sms_state('a1d0c6e83f027327d8461063f4ac58a6')
'arrived' # alternatively: "new" or "processed"
```
Similar to `send_sms`, `check_sms_state` accepts also `fail_silently` and
`timeout` parameters:
```python
check_sms_state('a1d0c6e83f027327d8461063f4ac58a6', timeout=30,
fail_silently=True)
```
#### Waiting for a message to arrive
In order to wait for the message to arrive user can use `wait_until_arrived`
function:
```python
>>> from sms_plusserver import wait_until_arrived
>>> wait_until_arrived('a1d0c6e83f027327d8461063f4ac58a6')
'arrived' # alternatively: "new" or "processed"
```
This function continuously checks state of given message until the service
responds with "arrived" status.
`wait_until_arrived` receives the same parameters as `send_sms_state`, but
meaning of `timeout` is a bit different - timeout is handled as total number
of seconds to wait for a message to arrive. Without explicit timeout,
this function can wait forever.
```python
check_sms_state('a1d0c6e83f027327d8461063f4ac58a6', timeout=120)
```
#### Using Object-Oriented API
All functions of `sms_plusserver` package can be accessed using object-oriented
API - `SMS` class:
```python
>>> from sms_plusserver import SMS
>>> sms = SMS('+4911122233344', 'Hello!')
>>> sms.send()
'a1d0c6e83f027327d8461063f4ac58a6'
>>> sms.check_state()
'arrived'
```
"Handle ID" and message state can be examined using `handle_id` and `state`
properties:
```python
>>> from sms_plusserver import SMS
>>> sms = SMS('+4911122233344', 'Hello!')
>>> sms.handle_id
None
>>> sms.send()
>>> sms.handle_id
'a1d0c6e83f027327d8461063f4ac58a6'
>>> sms.state
None
>>> sms.check_state()
>>> sms.state
'arrived'
```
All parameters available in module-level functions are also valid for
methods of `SMS` class:
```python
>>> from sms_plusserver import SMS
>>> sms = SMS('+4911122233344', 'Hello!')
>>> sms.send(fail_silently=True)
'a1d0c6e83f027327d8461063f4ac58a6'
>>> sms.check_state(wait=True, timeout=120) # Equivalent of `wait_until_arrived`
'arrived'
```
#### Multiple configurations
`sms_plusserver` supports global and local configurations.
By default, module level functions and classes use global configuration
(`sms_plusserver.default_service`) which can be altered using `configure` function.
To create independent configurations user can create new instance of `SMSService`
class and pass it to module-level functions or methods of `SMS` class
as `service` parameter:
```python
>>> from sms_plusserver import check_sms_state, SMS, SMSService
>>> service = SMSService(username='user', password='password', project='MyProject')
>>> sms = SMS('+4911122233344', 'Hello!')
>>> sms.send(service=service)
'a1d0c6e83f027327d8461063f4ac58a6'
>>> check_sms_state('a1d0c6e83f027327d8461063f4ac58a6', service=service)
'arrived'
```
#### SMS Response objects
All technical parameters returned by Plusserver API calls, can be inspected
by using `put_response` and `state_response` attributes of `SMS` objects.
#### Exceptions
`sms_plusserver` calls may raise the following exceptions:
* `ConfigurationError`: Service is improperly configured.
* `ValidationError`: Client-side error
* `CommunicationError`: Unable to communicate to API
* `RequestError`: API responded with an error
Requirements
------------
* Python 2.7+
* Python 3.5+
==============
Python library that allows to send messages using Plusserver SMS platform.
Installation
------------
```
pip install sms_plusserver
```
Usage
-----
In order to use this library users need to have an account on
Plusserver SMS platform (https://sms.openit.de/).
#### Quick start
`sms_plusserver` provides module-level convenience functions to make sending
messages easier:
```python
from sms_plusserver import configure, send_sms
# Configure service:
configure(username='user', password='pass')
# Send a message:
send_sms('+4911122233344', 'Hello!')
```
#### Configuration
`configure` function allows to set all configuration options. These options
will be used by other functions / classes of the module by default.
```python
from sms_plusserver import configure
configure(
# Your Plusserver credentials (required):
username='user',
password='pass',
# Optional parameters:
project='MyAppNotifications', # Name of your app / project
orig='MyApp', # SMS origin (name or phone number)
timeout=60 # Default timeout for service API calls
)
```
#### Sending messages
The easiest way to send a message is to call `send_sms` function:
```python
>>> from sms_plusserver import send_sms
>>> send_sms('+4911122233344', 'Hello!')
'a1d0c6e83f027327d8461063f4ac58a6' # Handle ID - unique message identifier
```
User can provide sender name or number in `orig` parameter:
```python
send_sms('+4911122233344', 'Hello!', orig='+4955544433300')
```
Messages on Plusserver platform can be tagged using `project` param:
```python
send_sms('+4911122233344', 'Hello!', project='MyProject')
```
By default all messages receive unique identifiers - "Handle ID".
This identifier allows user to check message status.
To send unregistered message user can set `registered_delivery` parameter
to `False`:
```python
>>> from sms_plusserver import send_sms
>>> send_sms('+4911122233344', 'Hello!', registered_delivery=False)
True # No "Handle ID", just True (message sent) or False (error)
```
In order to test SMS service without sending actual message, user can set
`debug` parameter to `True`. Debug messages will not receive "Handle ID":
```python
send_sms('+4911122233344', 'Hello!', debug=True)
```
All API calls are made using HTTP requests to Plusserver web API. User can
specify network timeout for each request:
```python
send_sms('+4911122233344', 'Hello!', timeout=30)
```
To silence exceptions raised due to network errors or errors returned from
provider's API, user can set `fail_silently` parameter to `True`:
```python
send_sms('+4911122233344', 'Hello!', fail_silently=True)
```
In this case, `send_sms` function will return `None` when error occurs.
#### Checking state of a message
To check status of a message with given "Handle ID" user can call
`check_sms_state` function:
```python
>>> from sms_plusserver import check_sms_state
>>> check_sms_state('a1d0c6e83f027327d8461063f4ac58a6')
'arrived' # alternatively: "new" or "processed"
```
Similar to `send_sms`, `check_sms_state` accepts also `fail_silently` and
`timeout` parameters:
```python
check_sms_state('a1d0c6e83f027327d8461063f4ac58a6', timeout=30,
fail_silently=True)
```
#### Waiting for a message to arrive
In order to wait for the message to arrive user can use `wait_until_arrived`
function:
```python
>>> from sms_plusserver import wait_until_arrived
>>> wait_until_arrived('a1d0c6e83f027327d8461063f4ac58a6')
'arrived' # alternatively: "new" or "processed"
```
This function continuously checks state of given message until the service
responds with "arrived" status.
`wait_until_arrived` receives the same parameters as `send_sms_state`, but
meaning of `timeout` is a bit different - timeout is handled as total number
of seconds to wait for a message to arrive. Without explicit timeout,
this function can wait forever.
```python
check_sms_state('a1d0c6e83f027327d8461063f4ac58a6', timeout=120)
```
#### Using Object-Oriented API
All functions of `sms_plusserver` package can be accessed using object-oriented
API - `SMS` class:
```python
>>> from sms_plusserver import SMS
>>> sms = SMS('+4911122233344', 'Hello!')
>>> sms.send()
'a1d0c6e83f027327d8461063f4ac58a6'
>>> sms.check_state()
'arrived'
```
"Handle ID" and message state can be examined using `handle_id` and `state`
properties:
```python
>>> from sms_plusserver import SMS
>>> sms = SMS('+4911122233344', 'Hello!')
>>> sms.handle_id
None
>>> sms.send()
>>> sms.handle_id
'a1d0c6e83f027327d8461063f4ac58a6'
>>> sms.state
None
>>> sms.check_state()
>>> sms.state
'arrived'
```
All parameters available in module-level functions are also valid for
methods of `SMS` class:
```python
>>> from sms_plusserver import SMS
>>> sms = SMS('+4911122233344', 'Hello!')
>>> sms.send(fail_silently=True)
'a1d0c6e83f027327d8461063f4ac58a6'
>>> sms.check_state(wait=True, timeout=120) # Equivalent of `wait_until_arrived`
'arrived'
```
#### Multiple configurations
`sms_plusserver` supports global and local configurations.
By default, module level functions and classes use global configuration
(`sms_plusserver.default_service`) which can be altered using `configure` function.
To create independent configurations user can create new instance of `SMSService`
class and pass it to module-level functions or methods of `SMS` class
as `service` parameter:
```python
>>> from sms_plusserver import check_sms_state, SMS, SMSService
>>> service = SMSService(username='user', password='password', project='MyProject')
>>> sms = SMS('+4911122233344', 'Hello!')
>>> sms.send(service=service)
'a1d0c6e83f027327d8461063f4ac58a6'
>>> check_sms_state('a1d0c6e83f027327d8461063f4ac58a6', service=service)
'arrived'
```
#### SMS Response objects
All technical parameters returned by Plusserver API calls, can be inspected
by using `put_response` and `state_response` attributes of `SMS` objects.
#### Exceptions
`sms_plusserver` calls may raise the following exceptions:
* `ConfigurationError`: Service is improperly configured.
* `ValidationError`: Client-side error
* `CommunicationError`: Unable to communicate to API
* `RequestError`: API responded with an error
Requirements
------------
* Python 2.7+
* Python 3.5+
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
sms_plusserver-0.1.1.tar.gz
(7.7 kB
view hashes)
Built Distribution
Close
Hashes for sms_plusserver-0.1.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 469672fa4118487b4d72b54bc84fac9dbbcf46c23a468911a6f3ebdbaea0c08d |
|
MD5 | 2ed6252838aa9cd845ba14160b9fd134 |
|
BLAKE2b-256 | 9bfe5b90bad5a5adaaf244467680f64f0b16867e4f44b90e6bdd131ad95f4acf |