# SWML Python SDK
The SWML Python SDK allows you to generate SWML (SignalWire Markup Language) in Python. SWML is a markup language used to control phone call behavior. This SDK provides classes for each SWML instruction and a convenient way to build sections and responses.
## Installation
You can install the SWML Python SDK via pip:
```bash
pip install swml-python
```
## Documentation
For more details on SWML, please visit the official
[SignalWire SWML documentation.](https://developer.signalwire.com/sdks/reference/swml/introduction)
## Getting Started
To generate SWML with the SDK, you'll first create an instance of SWMLResponse. This object represents an entire SWML response.
Within a response, you can create one or more **"sections"**. Each section is a collection of instructions that are
executed in when called. You create a section using the `add_section` method and give it a name:
```python
response = SignalWireML()
main_section = response.add_section('main')
other_section = response.add_section('other')
```
Additionally, you can create a section by creating an instance of the Section class and adding it to the `SignalWireML` object:
```python
main_section = Section('main')
response.add_section(main_section)
```
## Adding Instructions
Once you have a section, you can add instructions to it. Each instruction corresponds to a SWML verb, such as
**Answer**, **Hangup**, or **Play**. You can add an instruction using the corresponding method on the section object:
```python
response = SignalWireML()
main_section = response.add_section('main')
main_section.answer(max_duration=30)
main_section.play(url="https://example_1.com")
main_section.hangup()
```
In this example, we've added three instructions to the main section: an Answer instruction, a Play instruction,
and a Hangup instruction.
You can also add instructions by creating instances of the instruction classes and adding them to the section using the
**add_instruction** method. This is useful when you need to create complex instructions that have many parameters or if
you want to use the same instance declaration in multiple parts of your code:
```python
send_sms_instance = SendSMS(to_number="+1XXXXXXXXXX", from_="+1XXXXXXXXXX", body="Message Body", media=["url1", "url2"],
region="us", tags=["Custom", "data"])
main_section.add_instruction(send_sms_instance)
```
In addition, you can add raw SWML JSON to a section using the **add_instruction** method. This can be useful when you have
existing SWML JSON that you want to include in a section:
```python
raw_swml_json = '{"send_sms": {"to_number": "+1XXXXXXXXXX", "from": "+1XXXXXXXXXX", "body": "Message Body", "media": ["url1", "url2"], "region": "us", "tags": ["Custom", "data"]}}'
main_section.add_instruction(raw_swml_json)
```
**Warning:**
When adding raw SWML JSON, you must ensure that the JSON is valid. The SDK does not validate the JSON is valid SWML before
adding it to the section. This approach is flexible and allows the SDK to support new SWML instructions as they are
released, but it also allows you to add invalid SWML to a section. It is advised that you use the SDK methods to add
instructions whenever possible.
## Generating SWML
Once you've added all the desired sections and instructions, you can generate the SWML from the response using the
**generate_swml** method. This method has the option to output the SWML response in **JSON** or **YAML** format
(defaults to JSON) utilizing the **format** parameter:
```python
swml = response.generate_swml() # uses JSON as default
print(swml)
swml = response.generate_swml('yaml') # both 'json' and 'yaml' are valid values.
print(swml)
```
You can also convert the response directly to a string to get a json response:
```python
response = SignalWireML()
main_section = response.add_section('main')
main_section.answer()
main_section.hangup()
print(str(response))
```
This will output a string of SWML that represents the response.
## Full Example
Here's a full example that puts everything together:
```python
from swml import *
response = SignalWireML()
main_section = response.add_section("main")
main_section.answer()
main_section.record(stereo=True, format_='mp3')
# Add the prompt instruction
prompt_instruction = Prompt(
play="say:Please say an input",
say_language="en-US",
max_digits=1,
speech_hints=["one", "two", "three", "four", "five", "six", "seven", "eight", "nine"],
)
main_section.add_instruction(prompt_instruction)
# Add the switch instruction
switch_instruction = Switch(
variable="prompt_value",
case={
"1": [Transfer(dest="sales")],
"one": [Transfer(dest="sales")]
},
default=[
Play(url="say:That was a bad input, please try again!"),
Transfer(dest="main")
]
)
main_section.add_instruction(switch_instruction)
sales_section = response.add_section('sales')
sales_section.play(url='say:Welcome to Sales')
sales_section.prompt(
play='say:Pick a number between 1 and 3',
say_language="en-US",
max_digits=1,
speech_hints=["one", "two", "three"]
)
sales_case = {
'1': [Play(url="say:Case 1 was chosen"), Hangup()],
'one': [Play(url="say:Case one was chosen"), Hangup()],
'2': [Play(url='say:Case 2 was chosen'), Hangup()],
'two': [Play(url='say:Case two was chosen'), Hangup()],
'3': [Play(url='say:Case 3 was chosen'), Hangup()],
'three': [Play(url='say:Case three was chosen'), Hangup()]
}
sales_section.switch(variable='prompt_value', case=sales_case, default=[Transfer(dest='sales')])
swml = response.generate_swml(data_format='yaml')
print(swml)
```
Which will give the following yaml output:
```yaml
sections:
main:
- answer
- record:
stereo: true
format: mp3
- prompt:
play: say:Please say an input
say_language: en-US
max_digits: 1
speech_hints:
- one
- two
- three
- four
- five
- six
- seven
- eight
- nine
- switch:
variable: prompt_value
case:
'1':
- transfer:
dest: sales
one:
- transfer:
dest: sales
default:
- play:
url: say:That was a bad input, please try again!
- transfer:
dest: main
sales:
- play:
url: say:Welcome to Sales
- prompt:
play: say:Pick a number between 1 and 3
say_language: en-US
max_digits: 1
speech_hints:
- one
- two
- three
- switch:
variable: prompt_value
case:
'1':
- play:
url: say:Case 1 was chosen
- hangup
one:
- play:
url: say:Case one was chosen
- hangup
'2':
- play:
url: say:Case 2 was chosen
- hangup
two:
- play:
url: say:Case two was chosen
- hangup
'3':
- play:
url: say:Case 3 was chosen
- hangup
three:
- play:
url: say:Case three was chosen
- hangup
default:
- transfer:
dest: sales
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Devon-White/SWML-python",
"name": "swml-python",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Devon White",
"author_email": "devon.white@signalwire.com",
"download_url": "https://files.pythonhosted.org/packages/5b/b1/8db86b92309b0859d3b94b8591e2bf8c7f8cd49c41f56f4b9f753869b7cd/swml-python-1.0.tar.gz",
"platform": null,
"description": "# SWML Python SDK\r\n\r\nThe SWML Python SDK allows you to generate SWML (SignalWire Markup Language) in Python. SWML is a markup language used to control phone call behavior. This SDK provides classes for each SWML instruction and a convenient way to build sections and responses.\r\n\r\n## Installation\r\n\r\nYou can install the SWML Python SDK via pip:\r\n\r\n```bash\r\npip install swml-python\r\n```\r\n\r\n## Documentation\r\nFor more details on SWML, please visit the official \r\n[SignalWire SWML documentation.](https://developer.signalwire.com/sdks/reference/swml/introduction)\r\n\r\n## Getting Started\r\nTo generate SWML with the SDK, you'll first create an instance of SWMLResponse. This object represents an entire SWML response.\r\n\r\nWithin a response, you can create one or more **\"sections\"**. Each section is a collection of instructions that are \r\nexecuted in when called. You create a section using the `add_section` method and give it a name:\r\n\r\n```python\r\nresponse = SignalWireML()\r\nmain_section = response.add_section('main')\r\nother_section = response.add_section('other')\r\n```\r\n\r\nAdditionally, you can create a section by creating an instance of the Section class and adding it to the `SignalWireML` object:\r\n\r\n```python\r\nmain_section = Section('main')\r\nresponse.add_section(main_section)\r\n```\r\n\r\n## Adding Instructions\r\n\r\nOnce you have a section, you can add instructions to it. Each instruction corresponds to a SWML verb, such as \r\n**Answer**, **Hangup**, or **Play**. You can add an instruction using the corresponding method on the section object:\r\n\r\n```python\r\nresponse = SignalWireML()\r\nmain_section = response.add_section('main')\r\nmain_section.answer(max_duration=30)\r\nmain_section.play(url=\"https://example_1.com\")\r\nmain_section.hangup()\r\n```\r\n\r\nIn this example, we've added three instructions to the main section: an Answer instruction, a Play instruction, \r\nand a Hangup instruction.\r\n\r\n\r\nYou can also add instructions by creating instances of the instruction classes and adding them to the section using the\r\n**add_instruction** method. This is useful when you need to create complex instructions that have many parameters or if \r\nyou want to use the same instance declaration in multiple parts of your code:\r\n\r\n```python\r\nsend_sms_instance = SendSMS(to_number=\"+1XXXXXXXXXX\", from_=\"+1XXXXXXXXXX\", body=\"Message Body\", media=[\"url1\", \"url2\"],\r\n region=\"us\", tags=[\"Custom\", \"data\"])\r\nmain_section.add_instruction(send_sms_instance)\r\n```\r\n\r\nIn addition, you can add raw SWML JSON to a section using the **add_instruction** method. This can be useful when you have\r\nexisting SWML JSON that you want to include in a section:\r\n\r\n```python\r\nraw_swml_json = '{\"send_sms\": {\"to_number\": \"+1XXXXXXXXXX\", \"from\": \"+1XXXXXXXXXX\", \"body\": \"Message Body\", \"media\": [\"url1\", \"url2\"], \"region\": \"us\", \"tags\": [\"Custom\", \"data\"]}}'\r\nmain_section.add_instruction(raw_swml_json)\r\n```\r\n\r\n**Warning:**\r\n\r\nWhen adding raw SWML JSON, you must ensure that the JSON is valid. The SDK does not validate the JSON is valid SWML before\r\nadding it to the section. This approach is flexible and allows the SDK to support new SWML instructions as they are\r\nreleased, but it also allows you to add invalid SWML to a section. It is advised that you use the SDK methods to add\r\ninstructions whenever possible.\r\n\r\n\r\n## Generating SWML\r\nOnce you've added all the desired sections and instructions, you can generate the SWML from the response using the \r\n**generate_swml** method. This method has the option to output the SWML response in **JSON** or **YAML** format \r\n(defaults to JSON) utilizing the **format** parameter:\r\n\r\n```python\r\nswml = response.generate_swml() # uses JSON as default\r\nprint(swml)\r\n\r\nswml = response.generate_swml('yaml') # both 'json' and 'yaml' are valid values.\r\nprint(swml)\r\n```\r\n\r\nYou can also convert the response directly to a string to get a json response:\r\n\r\n```python\r\nresponse = SignalWireML()\r\nmain_section = response.add_section('main')\r\nmain_section.answer()\r\nmain_section.hangup()\r\n\r\nprint(str(response))\r\n```\r\n\r\nThis will output a string of SWML that represents the response.\r\n\r\n## Full Example\r\n\r\nHere's a full example that puts everything together:\r\n\r\n```python\r\nfrom swml import *\r\n\r\nresponse = SignalWireML()\r\n\r\nmain_section = response.add_section(\"main\")\r\nmain_section.answer()\r\n\r\nmain_section.record(stereo=True, format_='mp3')\r\n# Add the prompt instruction\r\nprompt_instruction = Prompt(\r\n play=\"say:Please say an input\",\r\n say_language=\"en-US\",\r\n max_digits=1,\r\n speech_hints=[\"one\", \"two\", \"three\", \"four\", \"five\", \"six\", \"seven\", \"eight\", \"nine\"],\r\n)\r\nmain_section.add_instruction(prompt_instruction)\r\n\r\n# Add the switch instruction\r\nswitch_instruction = Switch(\r\n variable=\"prompt_value\",\r\n case={\r\n \"1\": [Transfer(dest=\"sales\")],\r\n \"one\": [Transfer(dest=\"sales\")]\r\n },\r\n default=[\r\n Play(url=\"say:That was a bad input, please try again!\"),\r\n Transfer(dest=\"main\")\r\n ]\r\n)\r\nmain_section.add_instruction(switch_instruction)\r\nsales_section = response.add_section('sales')\r\nsales_section.play(url='say:Welcome to Sales')\r\nsales_section.prompt(\r\n play='say:Pick a number between 1 and 3',\r\n say_language=\"en-US\",\r\n max_digits=1,\r\n speech_hints=[\"one\", \"two\", \"three\"]\r\n)\r\n\r\nsales_case = {\r\n '1': [Play(url=\"say:Case 1 was chosen\"), Hangup()],\r\n 'one': [Play(url=\"say:Case one was chosen\"), Hangup()],\r\n '2': [Play(url='say:Case 2 was chosen'), Hangup()],\r\n 'two': [Play(url='say:Case two was chosen'), Hangup()],\r\n '3': [Play(url='say:Case 3 was chosen'), Hangup()],\r\n 'three': [Play(url='say:Case three was chosen'), Hangup()]\r\n\r\n}\r\nsales_section.switch(variable='prompt_value', case=sales_case, default=[Transfer(dest='sales')])\r\n\r\nswml = response.generate_swml(data_format='yaml')\r\nprint(swml)\r\n```\r\n\r\nWhich will give the following yaml output:\r\n\r\n```yaml\r\nsections:\r\n main:\r\n - answer\r\n - record:\r\n stereo: true\r\n format: mp3\r\n - prompt:\r\n play: say:Please say an input\r\n say_language: en-US\r\n max_digits: 1\r\n speech_hints:\r\n - one\r\n - two\r\n - three\r\n - four\r\n - five\r\n - six\r\n - seven\r\n - eight\r\n - nine\r\n - switch:\r\n variable: prompt_value\r\n case:\r\n '1':\r\n - transfer:\r\n dest: sales\r\n one:\r\n - transfer:\r\n dest: sales\r\n default:\r\n - play:\r\n url: say:That was a bad input, please try again!\r\n - transfer:\r\n dest: main\r\n sales:\r\n - play:\r\n url: say:Welcome to Sales\r\n - prompt:\r\n play: say:Pick a number between 1 and 3\r\n say_language: en-US\r\n max_digits: 1\r\n speech_hints:\r\n - one\r\n - two\r\n - three\r\n - switch:\r\n variable: prompt_value\r\n case:\r\n '1':\r\n - play:\r\n url: say:Case 1 was chosen\r\n - hangup\r\n one:\r\n - play:\r\n url: say:Case one was chosen\r\n - hangup\r\n '2':\r\n - play:\r\n url: say:Case 2 was chosen\r\n - hangup\r\n two:\r\n - play:\r\n url: say:Case two was chosen\r\n - hangup\r\n '3':\r\n - play:\r\n url: say:Case 3 was chosen\r\n - hangup\r\n three:\r\n - play:\r\n url: say:Case three was chosen\r\n - hangup\r\n default:\r\n - transfer:\r\n dest: sales\r\n```\r\n",
"bugtrack_url": null,
"license": "LICENSE.txt",
"summary": "A Python wrapper for the new SignalWire product SWML (SignalWire MarkUp Language)",
"version": "1.0",
"project_urls": {
"Homepage": "https://github.com/Devon-White/SWML-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5bb18db86b92309b0859d3b94b8591e2bf8c7f8cd49c41f56f4b9f753869b7cd",
"md5": "a2da2354e903c4869f02b3304f05ba72",
"sha256": "d5638879a287fa18ce200f913a60eb2e30405471007e06dc4d5ad969ef55d9b8"
},
"downloads": -1,
"filename": "swml-python-1.0.tar.gz",
"has_sig": false,
"md5_digest": "a2da2354e903c4869f02b3304f05ba72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13478,
"upload_time": "2023-11-06T16:58:34",
"upload_time_iso_8601": "2023-11-06T16:58:34.604185Z",
"url": "https://files.pythonhosted.org/packages/5b/b1/8db86b92309b0859d3b94b8591e2bf8c7f8cd49c41f56f4b9f753869b7cd/swml-python-1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-06 16:58:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Devon-White",
"github_project": "SWML-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "swml-python"
}
JSON
