# reach-python
## Documentation
The documentation for the Reach@Talkylabs API can be found [here][apidocs].
The Python library documentation can be found [here][libdocs].
## Versions
`reach-python` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details.
### Supported Python Versions
This library supports the following Python implementations:
- Python 3.7
- Python 3.8
- Python 3.9
- Python 3.10
- Python 3.11
## Installation
Install from PyPi using [pip](https://pip.pypa.io/en/latest/), a
package manager for Python.
```shell
pip3 install reach-talkylabs
```
If pip install fails on Windows, check the path length of the directory. If it is greater 260 characters then enable [Long Paths](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation) or choose other shorter location.
Don't have pip installed? Try installing it, by running this from the command
line:
```shell
curl https://bootstrap.pypa.io/get-pip.py | python
```
Or, you can [download the source code
(ZIP)](https://github.com/talkylabs/reach-python/zipball/main 'reach-python
source code') for `reach-python`, and then run:
```shell
python3 setup.py install
```
> **Info**
> If the command line gives you an error message that says Permission Denied, try running the above commands with `sudo` (e.g., `sudo pip3 install reach-talkylabs`).
### Test your installation
Try sending yourself an SMS message. Save the following code sample to your computer with a text editor. Be sure to update the `src` phone number with one that you verified in the web application. The `dest` phone number will be your own mobile phone.
```python
from talkylabs.reach.rest import ReachClient
api_user = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
api_key = "your_api_key"
client = ReachClient(api_user, api_key)
message = client.messaging.messaging_items.send(
dest="+15558675309",
src="+15017250604",
body="Hello from Python!")
print(message)
```
Save the file as `send_sms.py`. In the terminal, `cd` to the directory containing the file you just saved then run:
```shell
python3 send_sms.py
```
After a brief delay, you will receive the text message on your phone.
> **Warning**
> It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production.
## Use the helper library
### API Credentials
The client needs your Reach credentials. You can either pass these directly to the constructor (see the code below) or via environment variables.
Authenticating with Account SID and Auth Token:
```python
from talkylabs.reach.rest import ReachClient
api_user = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
api_key = "your_api_key"
client = ReachClient(api_user, api_key)
```
Alternatively, a `Client` constructor without these parameters will
look for `REACH_TALKYLABS_API_USER` and `REACH_TALKYLABS_API_KEY` variables inside the
current environment.
We suggest storing your credentials as environment variables. Why? You'll never
have to worry about committing your credentials and accidentally posting them
somewhere public.
```python
from talkylabs.reach.rest import ReachClient
client = ReachClient()
```
### Iterate through records
The library automatically handles paging for you. Collections, such as `calls` and `messages`, have `list` and `stream` methods that page under the hood. With both `list` and `stream`, you can specify the number of records you want to receive (`limit`) and the maximum size you want each page fetch to be (`page_size`). The library will then handle the task for you.
`list` eagerly fetches all records and returns them as a list, whereas `stream` returns an iterator and lazily retrieves pages of records as you iterate over the collection. You can also page manually using the `page` method.
#### Use the `list` method
```python
from talkylabs.reach.rest import ReachClient
api_user = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
api_key = "your_api_key"
client = ReachClient(api_user, api_key)
for sms in client.messaging.messaging_items.list():
print(sms.dest)
```
### Asynchronous API Requests
By default, the Client will make synchronous requests to the API. To allow for asynchronous, non-blocking requests, we've included an optional asynchronous HTTP client. When used with the Client and the accompanying `*_async` methods, requests made to the API will be performed asynchronously.
```python
from talkylabs.reach.http.async_http_client import AsyncReachHttpClient
from talkylabs.reach.rest import ReachClient
async def main():
api_user = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
api_key = "your_api_key"
http_client = AsyncReachHttpReachClient()
client = ReachClient(api_user, api_key, http_client=http_client)
message = await client.messaging.messaging_items.send_async(dest="+12316851234", src="+15555555555", body="Hello there!")
asyncio.run(main())
```
### Enable Debug Logging
Log the API request and response data to the console:
```python
import logging
client = ReachClient(api_user, api_key)
logging.basicConfig()
client.http_client.logger.setLevel(logging.INFO)
```
Log the API request and response data to a file:
```python
import logging
client = ReachClient(api_user, api_key)
logging.basicConfig(filename='./log.txt')
client.http_client.logger.setLevel(logging.INFO)
```
### Handling Exceptions
`reach-python` exports an exception class to help you handle exceptions that are specific to Reach methods. To use it, import `ReachRestException` and catch exceptions as follows:
```python
from talkylabs.reach.rest import ReachClient
from talkylabs.reach.base.exceptions import ReachRestException
api_user = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
api_key = "your_api_key"
client = ReachClient(api_user, api_key)
try:
message = client.messaging.messaging_items.send(dest="+12316851234", src="+15555555555", body="Hello there!")
except ReachRestException as e:
print(e)
```
### Other advanced examples
- [Learn how to create your own custom HTTP client](./advanced-examples/custom-http-client.md)
### Docker Image
The `Dockerfile` present in this repository and its respective `talkylabs/reach-python` Docker image are currently used by us for testing purposes only.
### Getting help
If you've found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!
[apidocs]: https://www.reach.talkylabs.com/docs/api
[libdocs]: https://talkylabs.github.io/reach-python
Raw data
{
"_id": null,
"home_page": "https://github.com/talkylabs/reach-python/",
"name": "reach-talkylabs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.0",
"maintainer_email": "",
"keywords": "reach-talkylabs",
"author": "Talkylabs",
"author_email": "help@talkylabs.com",
"download_url": "https://files.pythonhosted.org/packages/fb/bc/b71559947ca62554d015346d384885920fcfd5996e3fc6c39efc8ab43eb5/reach-talkylabs-1.0.0.tar.gz",
"platform": null,
"description": "# reach-python\n\n## Documentation\n\nThe documentation for the Reach@Talkylabs API can be found [here][apidocs].\n\nThe Python library documentation can be found [here][libdocs].\n\n## Versions\n\n`reach-python` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details.\n\n### Supported Python Versions\n\nThis library supports the following Python implementations:\n\n- Python 3.7\n- Python 3.8\n- Python 3.9\n- Python 3.10\n- Python 3.11\n\n## Installation\n\nInstall from PyPi using [pip](https://pip.pypa.io/en/latest/), a\npackage manager for Python.\n\n```shell\npip3 install reach-talkylabs\n```\n\nIf pip install fails on Windows, check the path length of the directory. If it is greater 260 characters then enable [Long Paths](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation) or choose other shorter location.\n\nDon't have pip installed? Try installing it, by running this from the command\nline:\n\n```shell\ncurl https://bootstrap.pypa.io/get-pip.py | python\n```\n\nOr, you can [download the source code\n(ZIP)](https://github.com/talkylabs/reach-python/zipball/main 'reach-python\nsource code') for `reach-python`, and then run:\n\n```shell\npython3 setup.py install\n```\n\n> **Info**\n> If the command line gives you an error message that says Permission Denied, try running the above commands with `sudo` (e.g., `sudo pip3 install reach-talkylabs`).\n\n### Test your installation\n\nTry sending yourself an SMS message. Save the following code sample to your computer with a text editor. Be sure to update the `src` phone number with one that you verified in the web application. The `dest` phone number will be your own mobile phone.\n\n```python\nfrom talkylabs.reach.rest import ReachClient\n\napi_user = \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\napi_key = \"your_api_key\"\n\nclient = ReachClient(api_user, api_key)\n\nmessage = client.messaging.messaging_items.send(\n dest=\"+15558675309\",\n src=\"+15017250604\",\n body=\"Hello from Python!\")\n\nprint(message)\n```\n\nSave the file as `send_sms.py`. In the terminal, `cd` to the directory containing the file you just saved then run:\n\n```shell\npython3 send_sms.py\n```\n\nAfter a brief delay, you will receive the text message on your phone.\n\n> **Warning**\n> It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production.\n\n## Use the helper library\n\n### API Credentials\n\nThe client needs your Reach credentials. You can either pass these directly to the constructor (see the code below) or via environment variables.\n\nAuthenticating with Account SID and Auth Token:\n\n```python\nfrom talkylabs.reach.rest import ReachClient\n\napi_user = \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\napi_key = \"your_api_key\"\nclient = ReachClient(api_user, api_key)\n```\n\nAlternatively, a `Client` constructor without these parameters will\nlook for `REACH_TALKYLABS_API_USER` and `REACH_TALKYLABS_API_KEY` variables inside the\ncurrent environment.\n\nWe suggest storing your credentials as environment variables. Why? You'll never\nhave to worry about committing your credentials and accidentally posting them\nsomewhere public.\n\n```python\nfrom talkylabs.reach.rest import ReachClient\nclient = ReachClient()\n```\n\n\n\n### Iterate through records\n\nThe library automatically handles paging for you. Collections, such as `calls` and `messages`, have `list` and `stream` methods that page under the hood. With both `list` and `stream`, you can specify the number of records you want to receive (`limit`) and the maximum size you want each page fetch to be (`page_size`). The library will then handle the task for you.\n\n`list` eagerly fetches all records and returns them as a list, whereas `stream` returns an iterator and lazily retrieves pages of records as you iterate over the collection. You can also page manually using the `page` method.\n\n#### Use the `list` method\n\n```python\nfrom talkylabs.reach.rest import ReachClient\n\napi_user = \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\napi_key = \"your_api_key\"\nclient = ReachClient(api_user, api_key)\n\nfor sms in client.messaging.messaging_items.list():\n print(sms.dest)\n```\n\n### Asynchronous API Requests\n\nBy default, the Client will make synchronous requests to the API. To allow for asynchronous, non-blocking requests, we've included an optional asynchronous HTTP client. When used with the Client and the accompanying `*_async` methods, requests made to the API will be performed asynchronously.\n\n```python\nfrom talkylabs.reach.http.async_http_client import AsyncReachHttpClient\nfrom talkylabs.reach.rest import ReachClient\n\nasync def main():\n api_user = \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n api_key = \"your_api_key\"\n http_client = AsyncReachHttpReachClient()\n client = ReachClient(api_user, api_key, http_client=http_client)\n\n message = await client.messaging.messaging_items.send_async(dest=\"+12316851234\", src=\"+15555555555\", body=\"Hello there!\")\n\nasyncio.run(main())\n```\n\n### Enable Debug Logging\n\nLog the API request and response data to the console:\n\n```python\nimport logging\n\nclient = ReachClient(api_user, api_key)\nlogging.basicConfig()\nclient.http_client.logger.setLevel(logging.INFO)\n```\n\nLog the API request and response data to a file:\n\n```python\nimport logging\n\nclient = ReachClient(api_user, api_key)\nlogging.basicConfig(filename='./log.txt')\nclient.http_client.logger.setLevel(logging.INFO)\n```\n\n### Handling Exceptions\n\n`reach-python` exports an exception class to help you handle exceptions that are specific to Reach methods. To use it, import `ReachRestException` and catch exceptions as follows:\n\n```python\nfrom talkylabs.reach.rest import ReachClient\nfrom talkylabs.reach.base.exceptions import ReachRestException\n\napi_user = \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\napi_key = \"your_api_key\"\nclient = ReachClient(api_user, api_key)\n\ntry:\n message = client.messaging.messaging_items.send(dest=\"+12316851234\", src=\"+15555555555\", body=\"Hello there!\")\nexcept ReachRestException as e:\n print(e)\n```\n\n\n### Other advanced examples\n\n- [Learn how to create your own custom HTTP client](./advanced-examples/custom-http-client.md)\n\n### Docker Image\n\nThe `Dockerfile` present in this repository and its respective `talkylabs/reach-python` Docker image are currently used by us for testing purposes only.\n\n### Getting help\n\nIf you've found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!\n\n[apidocs]: https://www.reach.talkylabs.com/docs/api\n[libdocs]: https://talkylabs.github.io/reach-python\n",
"bugtrack_url": null,
"license": "",
"summary": "Reach@Talkylabs API client",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/talkylabs/reach-python/"
},
"split_keywords": [
"reach-talkylabs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c859f284dd0fdce3ff8c6a2c9d5b6aef9a14e3fcfce1d483ed773c2590329901",
"md5": "574a7c3ce00973c22c48c11e551eefc7",
"sha256": "425153fbd9b8c5138bf940eb75d34a2300874b8814dec8d8b30c45b0e86a1e92"
},
"downloads": -1,
"filename": "reach_talkylabs-1.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "574a7c3ce00973c22c48c11e551eefc7",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7.0",
"size": 57348,
"upload_time": "2023-09-22T21:16:55",
"upload_time_iso_8601": "2023-09-22T21:16:55.227343Z",
"url": "https://files.pythonhosted.org/packages/c8/59/f284dd0fdce3ff8c6a2c9d5b6aef9a14e3fcfce1d483ed773c2590329901/reach_talkylabs-1.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fbbcb71559947ca62554d015346d384885920fcfd5996e3fc6c39efc8ab43eb5",
"md5": "8f41eee2bc53d685b59989997e661687",
"sha256": "d264180c1b449dbf4f67997498e52f257af55e830749894f11fae8a4b998b4aa"
},
"downloads": -1,
"filename": "reach-talkylabs-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8f41eee2bc53d685b59989997e661687",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.0",
"size": 35706,
"upload_time": "2023-09-22T21:16:56",
"upload_time_iso_8601": "2023-09-22T21:16:56.775778Z",
"url": "https://files.pythonhosted.org/packages/fb/bc/b71559947ca62554d015346d384885920fcfd5996e3fc6c39efc8ab43eb5/reach-talkylabs-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-22 21:16:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "talkylabs",
"github_project": "reach-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"tox": true,
"lcname": "reach-talkylabs"
}
JSON
