# Telnyx Python Library
[][pypi]
[][pypi]
[][pypi]
[][Actions]
[][coveralls]
[](https://joinslack.telnyx.com/)
[pypi]: https://pypi.org/project/telnyx/
[Actions]: https://github.com/team-telnyx/telnyx-python/actions
[coveralls]: https://coveralls.io/github/team-telnyx/telnyx-python?branch=master
The Telnyx Python library provides convenient access to the Telnyx API from
applications written in the Python language. It includes a pre-defined set of
classes for API resources that initialize themselves dynamically from API
responses which makes it compatible with a wide range of versions of the Telnyx
API.
## Documentation
See the [API Reference](https://developers.telnyx.com/docs/api/v2/overview) and the [Setup Guides](https://developers.telnyx.com/docs/v2/development/dev-env-setup).
## Installation
You don't need this source code unless you want to modify the package. If you just
want to use the package, just run:
pip install --upgrade telnyx
Install from source with:
python setup.py install
### Non x86/x86_64 Processors
The `telnyx` package is distributed as a wheel (pre-compiled package) for easy
installation. The wheel is built only for x86/x86_64 processors. When
installing the package on a different architecture, like ARM, the `pip`
installer will fall back to installing from source. As a result, you will
need to ensure you have the additional dependencies installed. This will
affect you if you're using a Raspberry Pi, for example.
For ARM specifically, as an alternative to a source install, you could look
into using https://www.piwheels.org/ for ARM compiled wheels.
### Requirements
- Python 3.8+ (PyPy supported)
#### Additional Requirements for Source Install
- build-essentials (gcc, make)
- python-dev
- libffi-dev
_These packages are listed as they are named on Ubuntu._
## Usage
The library needs to be configured with your account's API Key which is
available in your [Telnyx Dashboard][api-keys]. Set `telnyx.api_key` to its
value:
```python
import telnyx
telnyx.api_key = "KEY01234_yoursecretkey"
# Retrieve single Messaging Profile
telnyx.MessagingProfile.retrieve("123")
# List Messaging Profiles
profiles = telnyx.MessagingProfile.list()
# Retrieve next page of list results
profiles.next_page()
# Loop over all page results
for page in profiles.auto_paging_iter():
print(page)
```
You can read more about our API Keys [here](https://developers.telnyx.com/docs/v2/development/authentication).
### Per-Request Configuration
For apps that need to use multiple keys during the lifetime of a process,
it's also possible to set a per-request key and/or account:
```python
import telnyx
# list messaging profiles
telnyx.MessagingProfile.list(
api_key="super-secret...",
)
# retrieve single messaging profile
telnyx.MessagingProfile.retrieve(
"123",
api_key="other-secret...",
)
```
### Configuring an HTTP Client
The library can be configured to use `urlfetch`, `requests`, `pycurl`, or
`urllib2` with `telnyx.default_http_client`:
```python
client = telnyx.http_client.UrlFetchClient()
client = telnyx.http_client.RequestsClient()
client = telnyx.http_client.PycurlClient()
client = telnyx.http_client.Urllib2Client()
telnyx.default_http_client = client
```
Without a configured client, by default the library will attempt to load
libraries in the order above (i.e. `urlfetch` is preferred with `urllib2` used
as a last resort). We usually recommend that people use `requests`.
### Configuring a Proxy
A proxy can be configured with `telnyx.proxy`:
```python
telnyx.proxy = "https://user:pass@example.com:1234"
```
### Configuring Automatic Retries
Number of automatic retries on requests that fail due to an intermittent
network problem can be configured:
```python
telnyx.max_network_retries = 2
```
### Reserved word keyword arguments
The Telnyx API includes `from` as an attribute that can be set on messages.
`from` is also a reserved word in Python. If you would like to use keyword
arguments where an argument is a reserved word you can add the suffix `_` e.g.
```
telnyx.Message.create(
to="+18665550001",
from_="+18445550001",
text="Foo"
)
```
The argument will be automatically rewritten to `from` in the keyword arguments dict.
> Pro Tip: You can alternatively unpack a dictionary like so:
>
> ```python
> message = {
> "from": "+18445550001",
> "to": "+18665550001",
> "text": "Foo",
> }
> telnyx.Message.create(**message)
> ```
### Logging
The library can be configured to emit logging that will give you better insight
into what it's doing. The `info` logging level is usually most appropriate for
production use, but `debug` is also available for more verbosity.
There are a few options for enabling it:
1. Set the environment variable `TELNYX_LOG` to the value `debug` or `info`
```
$ export TELNYX_LOG=debug
```
2. Set `telnyx.log`:
```py
import telnyx
telnyx.log = 'debug'
```
3. Enable it through Python's logging module:
```py
import logging
logging.basicConfig()
logging.getLogger('telnyx').setLevel(logging.DEBUG)
```
### Writing a Plugin
If you're writing a plugin that uses the library, we'd appreciate it if you
identified using `telnyx.set_app_info()`:
```py
telnyx.set_app_info("MyAwesomePlugin", version="1.2.34", url="https://myawesomeplugin.info")
```
This information is passed along when the library makes calls to the Telnyx
API.
## Development
The test suite depends on [telnyx-mock], so make sure to fetch and run it from a
background terminal ([telnyx-mock's README][telnyx-mock] also contains
instructions for installing via Homebrew and other methods):
go get -u github.com/team-telnyx/telnyx-mock
telnyx-mock
Install [pipenv][pipenv], then install all dependencies for the project:
pipenv install --dev
Run all tests on all supported Python versions:
make test
Run all tests for a specific Python version (modify `-e` according to your Python target):
pipenv run tox -e py38
Run all tests in a single file:
pipenv run tox -e py38 -- tests/api_resources/abstract/test_updateable_api_resource.py
Run a single test suite:
pipenv run tox -e py38 -- tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource
Run a single test:
pipenv run tox -e py38 -- tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource::test_save
Run the linter with:
make lint
The library uses [Black][black] for code formatting. Code must be formatted
with Black before PRs are submitted, otherwise CI will fail. Run the formatter
with:
make fmt
### Adding a new endpoint
1. Define a class for the object that the endpoint interacts with under
`telnyx/api_resources/`. The path name singularized should typically match
the record type of the object returned e.g. `/v2/available_phone_numbers`
returns a list of objects with the record_type `available_phone_number`.
Inherit from the classes that define the behavior available on the endpoint,one or more of `CreateableAPIResource`, `DeletableAPIResource`,
`ListableAPIResource`, `UpdateableAPIResource`.
2. Import your class in `telnyx/api_resources/__init__.py`.
3. Add your new class to the `OBJECT_CLASSES` block in `telnyx/util.py`.
4. Add tests for your new class under `tests/api_resources/`.
[api-keys]: https://portal.telnyx.com/#/app/auth/v2
[black]: https://github.com/ambv/black
[pipenv]: https://github.com/pypa/pipenv
[telnyx-mock]: https://github.com/team-telnyx/telnyx-mock
## Releasing
1. Update version in
- `setup.py` (in the `setup()` call, the `version` kwarg)
- `telnyx/__init__.py` (the `__version__` string)
2. Create new branch, add changes, commit, and push
3. Ensure commit passes tests in [Travis][travis-telnyx-python]
4. Tag that commit with `git tag -a v{VERSION} -m "Release v{VERSION}"`, and push the tag `git push --follow-tags`
5. Ensure checked out copy is entirely clean (best to create a new environment...)
6. `make dists`
7. _If you haven't done it before_, download the upload API keys from LastPass (search for "pypi") and put the contents between "PYPIRC FILE" tags into `~/.pypirc-telnyx`.
8. `make testupload`, check that it looks OK on PyPI and that it's installable via `pip`.
9. `make liveupload`, repeat checks for live version.
10. Ta-da.
[travis-telnyx-python]: https://travis-ci.org/team-telnyx/telnyx-python
## Acknowledgments
The contributors and maintainers of Telnyx Python would like to extend their
deep gratitude to the authors of [Stripe Python][stripe-python], upon which
this project is based. Thank you for developing such elegant, usable, and
extensible code and for sharing it with the community.
[stripe-python]: https://github.com/stripe/stripe-python
<!--
# vim: set tw=79:
-->
Raw data
{
"_id": null,
"home_page": "https://github.com/team-telnyx/telnyx-python",
"name": "telnyx",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "telnyx telephony sip networking callcontrol messaging sms mms",
"author": "Telnyx",
"author_email": "support@telnyx.com",
"download_url": "https://files.pythonhosted.org/packages/c8/ad/a9b6dde859440e0ee6fa17328be4a73168a3c1b38c98c64d1c7af257eb65/telnyx-2.1.1.tar.gz",
"platform": null,
"description": "# Telnyx Python Library\n\n[][pypi]\n[][pypi]\n[][pypi]\n[][Actions]\n[][coveralls]\n[](https://joinslack.telnyx.com/)\n\n[pypi]: https://pypi.org/project/telnyx/\n[Actions]: https://github.com/team-telnyx/telnyx-python/actions\n[coveralls]: https://coveralls.io/github/team-telnyx/telnyx-python?branch=master\n\nThe Telnyx Python library provides convenient access to the Telnyx API from\napplications written in the Python language. It includes a pre-defined set of\nclasses for API resources that initialize themselves dynamically from API\nresponses which makes it compatible with a wide range of versions of the Telnyx\nAPI.\n\n## Documentation\n\nSee the [API Reference](https://developers.telnyx.com/docs/api/v2/overview) and the [Setup Guides](https://developers.telnyx.com/docs/v2/development/dev-env-setup).\n\n## Installation\n\nYou don't need this source code unless you want to modify the package. If you just\nwant to use the package, just run:\n\n pip install --upgrade telnyx\n\nInstall from source with:\n\n python setup.py install\n\n### Non x86/x86_64 Processors\n\nThe `telnyx` package is distributed as a wheel (pre-compiled package) for easy\ninstallation. The wheel is built only for x86/x86_64 processors. When\ninstalling the package on a different architecture, like ARM, the `pip`\ninstaller will fall back to installing from source. As a result, you will\nneed to ensure you have the additional dependencies installed. This will\naffect you if you're using a Raspberry Pi, for example.\n\nFor ARM specifically, as an alternative to a source install, you could look\ninto using https://www.piwheels.org/ for ARM compiled wheels.\n\n### Requirements\n\n- Python 3.8+ (PyPy supported)\n\n#### Additional Requirements for Source Install\n\n- build-essentials (gcc, make)\n- python-dev\n- libffi-dev\n\n_These packages are listed as they are named on Ubuntu._\n\n## Usage\n\nThe library needs to be configured with your account's API Key which is\navailable in your [Telnyx Dashboard][api-keys]. Set `telnyx.api_key` to its\nvalue:\n\n```python\nimport telnyx\ntelnyx.api_key = \"KEY01234_yoursecretkey\"\n\n# Retrieve single Messaging Profile\ntelnyx.MessagingProfile.retrieve(\"123\")\n\n# List Messaging Profiles\nprofiles = telnyx.MessagingProfile.list()\n\n# Retrieve next page of list results\nprofiles.next_page()\n\n# Loop over all page results\nfor page in profiles.auto_paging_iter():\n print(page)\n```\n\nYou can read more about our API Keys [here](https://developers.telnyx.com/docs/v2/development/authentication).\n\n### Per-Request Configuration\n\nFor apps that need to use multiple keys during the lifetime of a process,\nit's also possible to set a per-request key and/or account:\n\n```python\nimport telnyx\n\n# list messaging profiles\ntelnyx.MessagingProfile.list(\n api_key=\"super-secret...\",\n)\n\n# retrieve single messaging profile\ntelnyx.MessagingProfile.retrieve(\n \"123\",\n api_key=\"other-secret...\",\n)\n```\n\n### Configuring an HTTP Client\n\nThe library can be configured to use `urlfetch`, `requests`, `pycurl`, or\n`urllib2` with `telnyx.default_http_client`:\n\n```python\nclient = telnyx.http_client.UrlFetchClient()\nclient = telnyx.http_client.RequestsClient()\nclient = telnyx.http_client.PycurlClient()\nclient = telnyx.http_client.Urllib2Client()\ntelnyx.default_http_client = client\n```\n\nWithout a configured client, by default the library will attempt to load\nlibraries in the order above (i.e. `urlfetch` is preferred with `urllib2` used\nas a last resort). We usually recommend that people use `requests`.\n\n### Configuring a Proxy\n\nA proxy can be configured with `telnyx.proxy`:\n\n```python\ntelnyx.proxy = \"https://user:pass@example.com:1234\"\n```\n\n### Configuring Automatic Retries\n\nNumber of automatic retries on requests that fail due to an intermittent\nnetwork problem can be configured:\n\n```python\ntelnyx.max_network_retries = 2\n```\n\n### Reserved word keyword arguments\n\nThe Telnyx API includes `from` as an attribute that can be set on messages.\n`from` is also a reserved word in Python. If you would like to use keyword\narguments where an argument is a reserved word you can add the suffix `_` e.g.\n\n```\ntelnyx.Message.create(\n to=\"+18665550001\",\n from_=\"+18445550001\",\n text=\"Foo\"\n)\n```\n\nThe argument will be automatically rewritten to `from` in the keyword arguments dict.\n\n> Pro Tip: You can alternatively unpack a dictionary like so:\n>\n> ```python\n> message = {\n> \"from\": \"+18445550001\",\n> \"to\": \"+18665550001\",\n> \"text\": \"Foo\",\n> }\n> telnyx.Message.create(**message)\n> ```\n\n### Logging\n\nThe library can be configured to emit logging that will give you better insight\ninto what it's doing. The `info` logging level is usually most appropriate for\nproduction use, but `debug` is also available for more verbosity.\n\nThere are a few options for enabling it:\n\n1. Set the environment variable `TELNYX_LOG` to the value `debug` or `info`\n\n ```\n $ export TELNYX_LOG=debug\n ```\n\n2. Set `telnyx.log`:\n\n ```py\n import telnyx\n telnyx.log = 'debug'\n ```\n\n3. Enable it through Python's logging module:\n ```py\n import logging\n logging.basicConfig()\n logging.getLogger('telnyx').setLevel(logging.DEBUG)\n ```\n\n### Writing a Plugin\n\nIf you're writing a plugin that uses the library, we'd appreciate it if you\nidentified using `telnyx.set_app_info()`:\n\n```py\ntelnyx.set_app_info(\"MyAwesomePlugin\", version=\"1.2.34\", url=\"https://myawesomeplugin.info\")\n```\n\nThis information is passed along when the library makes calls to the Telnyx\nAPI.\n\n## Development\n\nThe test suite depends on [telnyx-mock], so make sure to fetch and run it from a\nbackground terminal ([telnyx-mock's README][telnyx-mock] also contains\ninstructions for installing via Homebrew and other methods):\n\n go get -u github.com/team-telnyx/telnyx-mock\n telnyx-mock\n\nInstall [pipenv][pipenv], then install all dependencies for the project:\n\n pipenv install --dev\n\nRun all tests on all supported Python versions:\n\n make test\n\nRun all tests for a specific Python version (modify `-e` according to your Python target):\n\n pipenv run tox -e py38\n\nRun all tests in a single file:\n\n pipenv run tox -e py38 -- tests/api_resources/abstract/test_updateable_api_resource.py\n\nRun a single test suite:\n\n pipenv run tox -e py38 -- tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource\n\nRun a single test:\n\n pipenv run tox -e py38 -- tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource::test_save\n\nRun the linter with:\n\n make lint\n\nThe library uses [Black][black] for code formatting. Code must be formatted\nwith Black before PRs are submitted, otherwise CI will fail. Run the formatter\nwith:\n\n make fmt\n\n### Adding a new endpoint\n\n1. Define a class for the object that the endpoint interacts with under\n `telnyx/api_resources/`. The path name singularized should typically match\n the record type of the object returned e.g. `/v2/available_phone_numbers`\n returns a list of objects with the record_type `available_phone_number`.\n Inherit from the classes that define the behavior available on the endpoint,one or more of `CreateableAPIResource`, `DeletableAPIResource`,\n `ListableAPIResource`, `UpdateableAPIResource`.\n\n2. Import your class in `telnyx/api_resources/__init__.py`.\n\n3. Add your new class to the `OBJECT_CLASSES` block in `telnyx/util.py`.\n\n4. Add tests for your new class under `tests/api_resources/`.\n\n[api-keys]: https://portal.telnyx.com/#/app/auth/v2\n[black]: https://github.com/ambv/black\n[pipenv]: https://github.com/pypa/pipenv\n[telnyx-mock]: https://github.com/team-telnyx/telnyx-mock\n\n## Releasing\n\n1. Update version in\n - `setup.py` (in the `setup()` call, the `version` kwarg)\n - `telnyx/__init__.py` (the `__version__` string)\n2. Create new branch, add changes, commit, and push\n3. Ensure commit passes tests in [Travis][travis-telnyx-python]\n4. Tag that commit with `git tag -a v{VERSION} -m \"Release v{VERSION}\"`, and push the tag `git push --follow-tags`\n5. Ensure checked out copy is entirely clean (best to create a new environment...)\n6. `make dists`\n7. _If you haven't done it before_, download the upload API keys from LastPass (search for \"pypi\") and put the contents between \"PYPIRC FILE\" tags into `~/.pypirc-telnyx`.\n8. `make testupload`, check that it looks OK on PyPI and that it's installable via `pip`.\n9. `make liveupload`, repeat checks for live version.\n10. Ta-da.\n\n[travis-telnyx-python]: https://travis-ci.org/team-telnyx/telnyx-python\n\n## Acknowledgments\n\nThe contributors and maintainers of Telnyx Python would like to extend their\ndeep gratitude to the authors of [Stripe Python][stripe-python], upon which\nthis project is based. Thank you for developing such elegant, usable, and\nextensible code and for sharing it with the community.\n\n[stripe-python]: https://github.com/stripe/stripe-python\n\n<!--\n# vim: set tw=79:\n-->\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python bindings for the Telnyx API",
"version": "2.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/team-telnyx/telnyx-python/issues",
"Documentation": "https://developers.telnyx.com/docs/api/v2/overview",
"Homepage": "https://github.com/team-telnyx/telnyx-python",
"Source Code": "https://github.com/team-telnyx/telnyx-python"
},
"split_keywords": [
"telnyx",
"telephony",
"sip",
"networking",
"callcontrol",
"messaging",
"sms",
"mms"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "389dc19a74f56f3847cb964572d4e19cf4439e1db9126b45ad8d3106667f98ad",
"md5": "ea0e905f2a5f969b1688ee29ab7f1f4e",
"sha256": "f86d67cda147c2696ea631c1ae3df41be51d70c30f49ad62d2cfdcf96fdd6a5f"
},
"downloads": -1,
"filename": "telnyx-2.1.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea0e905f2a5f969b1688ee29ab7f1f4e",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 104398,
"upload_time": "2024-02-23T10:28:28",
"upload_time_iso_8601": "2024-02-23T10:28:28.529199Z",
"url": "https://files.pythonhosted.org/packages/38/9d/c19a74f56f3847cb964572d4e19cf4439e1db9126b45ad8d3106667f98ad/telnyx-2.1.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c8ada9b6dde859440e0ee6fa17328be4a73168a3c1b38c98c64d1c7af257eb65",
"md5": "9fc7202a0db1bf2265d164f1220e82c7",
"sha256": "bb01c77f9152a4a96e85373e772ce846eb1d5494d6688729dcc8e0d87218aaeb"
},
"downloads": -1,
"filename": "telnyx-2.1.1.tar.gz",
"has_sig": false,
"md5_digest": "9fc7202a0db1bf2265d164f1220e82c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 80667,
"upload_time": "2024-02-23T10:28:29",
"upload_time_iso_8601": "2024-02-23T10:28:29.786735Z",
"url": "https://files.pythonhosted.org/packages/c8/ad/a9b6dde859440e0ee6fa17328be4a73168a3c1b38c98c64d1c7af257eb65/telnyx-2.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-23 10:28:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "team-telnyx",
"github_project": "telnyx-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "telnyx"
}
JSON
