Skip to content

Commit c0ea4e2

Browse files
maxkahanmaxkahan
committed
add additional info to readme
1 parent ae5d9ef commit c0ea4e2

File tree

2 files changed

+174
-27
lines changed

2 files changed

+174
-27
lines changed

‎README.md

+123
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,18 @@
1111
The purpose of these Code Snippets is to provide simple examples focused
1212
on one goal. For example, sending an SMS, creating a Vonage Video API session, handling an incoming webhook, or making a Text-to-Speech call.
1313

14+
## Table of Contents
15+
16+
- [Setup](#setup)
17+
- [Running the Examples](#running-the-examples)
18+
- [SDK Structure](#sdk-structure)
19+
- [How the SDK Handles Errors](#how-the-sdk-handles-errors)
20+
- [Troubleshooting](#troubleshooting)
21+
- [Useful Resources](#useful-resources)
22+
- [Request an Example](#request-an-example)
23+
- [License](#license)
24+
- [Python Code Snippets](#python-code-snippets)
25+
1426
## Setup
1527

1628
These code samples are meant to be embedded into pages on [https://developer.vonage.com/](https://developer.vonage.com/). Developers are free to use these code snippets as a reference, but these may require changes to be worked into your specific application. We recommend checking out the [Vonage Developer Website](https://developer.vonage.com/), which displays these code snippets in a more copy/paste fashion.
@@ -57,6 +69,117 @@ For samples that require a web server, run with FastAPI, e.g.
5769
fastapi dev messages/inbound-message.py
5870
```
5971

72+
## SDK Structure
73+
74+
The SDK is a monorepo - lots of packages in a single place. In the SDK, we have:
75+
76+
1. The top-level package `vonage`, which pulls in all the other packages you need.
77+
1. A package referring to every API supported in the SDK (`vonage-sms`, `vonage-voice`, `vonage-video` etc.)
78+
1. Internal packages for making HTTP requests, creating JWTs etc. (`vonage-http-client`, `vonage-jwt` etc.)
79+
1. A utilities package (`vonage-utils`)
80+
81+
There are important things to note:
82+
83+
1. The `vonage` package instantiates each of the API packages. For example, you can call `vonage.voice.any_method_from_the_voice_class`. This means you don’t have to instantiate packages that you need separately.
84+
1. Many of the APIs require input data from the user. This is passed in through data models that you will find in the package for the specific API you want to call. This was intentional so the user doesn’t immediately import every data model from every single API whenever they import the top-level package, which would make it harder to find what is actually needed in an IDE, and allows for models with the same names in different namespaces.
85+
86+
For example, to use a `VerifyRequest` object from the `vonage-verify` package, you’ll need to first import the `vonage` package to get the `Auth` object and the `Verify` methods, then import `VerifyRequest` from the `vonage-verify` package, like so:
87+
88+
```python
89+
from vonage import Auth, Vonage
90+
from vonage_verify import VerifyRequest, SmsChannel
91+
92+
client = Vonage(
93+
Auth(
94+
application_id=VONAGE_APPLICATION_ID,
95+
private_key=VONAGE_APPLICATION_PRIVATE_KEY_PATH,
96+
)
97+
)
98+
99+
verify_request = VerifyRequest(
100+
brand=BRAND_NAME,
101+
workflow=[
102+
SmsChannel(to=TO_NUMBER),
103+
],
104+
)
105+
106+
response = vonage_client.verify.start_verification(verify_request)
107+
```
108+
109+
This is explained in more detail in the blog post shared above. You can also find full, working examples [in the Python Code Snippets repo](https://github.com/Vonage/vonage-python-code-snippets).
110+
111+
### Getting the Objects You Need Into Your Namespace
112+
113+
If you’re working with e.g. the Voice API, if you know you’re likely to use many of the data models, you can import them all into your app’s namespace (making it easier for your autocomplete etc. to find them) with the `*` operator, e.g.
114+
115+
```python
116+
from vonage_voice import *
117+
118+
request = CreateCallRequest(...)
119+
```
120+
121+
It’s usually considered better practice to import just what you need, but using this method means the data models will all be available to you if you need to do some quick testing.
122+
123+
## How the SDK handles errors
124+
125+
The Vonage Python SDK has various different classes of errors:
126+
127+
- Some regular Python/package errors that can be raised during the course of SDK operation
128+
- The top-level `VonageError`, that custom SDK errors inherit from
129+
- Errors raised when using some packages, e.g. `VerifyError`
130+
- Errors raised by the HTTP client
131+
132+
It’s likely that when troubleshooting, you’ll especially see HTTP request errors, so let’s discuss these.
133+
134+
### HTTP Request Errors
135+
136+
This is a class of errors raised when actually making the HTTP request or when receiving an HTTP response.
137+
138+
The high-level error here is the `HttpRequestError`. There are other errors which are based on this and have the same properties, but different names that are more specific to [the HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) received from the Vonage server, e.g. an `AuthenticationError` or a `NotFoundError`.
139+
140+
Each error of this type has properties that can be accessed when the error is caught, i.e. if you have a try-except block which catches an error, you can then access the error message and the response object which has additional information. This can be useful for debugging.
141+
142+
To catch an error in this way, do this:
143+
144+
```python
145+
try:
146+
vonage_client.call_vonage_api(...)
147+
except HttpRequestError as e:
148+
print(‘Request failed:’)
149+
print(e.message)
150+
print(e.response.text)
151+
```
152+
153+
You can access any information about the request or the response from the `e.response` object.
154+
155+
## Troubleshooting
156+
157+
### Viewing the last request and response
158+
159+
Whether or not an HTTP request was successful, you can access the last request and response sent by accessing the relevant HTTP client attributes like this:
160+
161+
```python
162+
vonage_client.http_client.last_request
163+
vonage_client.http_client.last_response
164+
```
165+
166+
For example, to see the last request body and headers sent by the SDK, you can do:
167+
168+
```python
169+
print(vonage_client.http_client.last_request.body)
170+
print(vonage_client.http_client.last_request.headers)
171+
```
172+
173+
### Authentication errors
174+
175+
If the SDK returns an `AuthenticationError`, this is because the Vonage Server was not able to authenticate the SDK user. In this case, you should check the authentication details that were provided.
176+
177+
## Useful Resources
178+
- [Vonage Python SDK on Github](https://github.com/Vonage/vonage-python-sdk)
179+
- [Vonage Python SDK on PyPI](https://pypi.org/project/vonage/)
180+
- [Python SDK introduction blog](https://developer.vonage.com/en/blog/vonage-python-sdk-v4-is-now-live-#getting-started)
181+
- [Migration guide from old to new SDK](https://github.com/Vonage/vonage-python-sdk/blob/main/V3_TO_V4_SDK_MIGRATION_GUIDE.md)
182+
60183
## Request an Example
61184

62185
Please [raise an issue](https://github.com/Vonage/vonage-python-code-snippets/issues) to request an example that isn't present within the quickstart. Pull requests will be gratefully received.

‎readme-base.md

+51-27
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,18 @@
1111
The purpose of these Code Snippets is to provide simple examples focused
1212
on one goal. For example, sending an SMS, creating a Vonage Video API session, handling an incoming webhook, or making a Text-to-Speech call.
1313

14+
## Table of Contents
15+
16+
- [Setup](#setup)
17+
- [Running the Examples](#running-the-examples)
18+
- [SDK Structure](#sdk-structure)
19+
- [How the SDK Handles Errors](#how-the-sdk-handles-errors)
20+
- [Troubleshooting](#troubleshooting)
21+
- [Useful Resources](#useful-resources)
22+
- [Request an Example](#request-an-example)
23+
- [License](#license)
24+
- [Python Code Snippets](#python-code-snippets)
25+
1426
## Setup
1527

1628
These code samples are meant to be embedded into pages on [https://developer.vonage.com/](https://developer.vonage.com/). Developers are free to use these code snippets as a reference, but these may require changes to be worked into your specific application. We recommend checking out the [Vonage Developer Website](https://developer.vonage.com/), which displays these code snippets in a more copy/paste fashion.
@@ -69,10 +81,11 @@ The SDK is a monorepo - lots of packages in a single place. In the SDK, we have:
6981
There are important things to note:
7082

7183
1. The `vonage` package instantiates each of the API packages. For example, you can call `vonage.voice.any_method_from_the_voice_class`. This means you don’t have to instantiate packages that you need separately.
72-
Many of the APIs require input data from the user. This is passed in through data models that you will find in the package for the specific API you want to call. This was intentional so the user doesn’t immediately import every data model from every single API whenever they import the top-level package, which would make it harder to find what is actually needed in an IDE, and allows for models with the same names in different namespaces.
84+
1. Many of the APIs require input data from the user. This is passed in through data models that you will find in the package for the specific API you want to call. This was intentional so the user doesn’t immediately import every data model from every single API whenever they import the top-level package, which would make it harder to find what is actually needed in an IDE, and allows for models with the same names in different namespaces.
7385

74-
For example, to use a `VerifyRequest` object from the vonage-verify package, you’ll need to first import the vonage package to get the auth objects and the Verify methods, then import VerifyRequest from the vonage-verify package, like so:
86+
For example, to use a `VerifyRequest` object from the `vonage-verify` package, you’ll need to first import the `vonage` package to get the `Auth` object and the `Verify` methods, then import `VerifyRequest` from the `vonage-verify` package, like so:
7587

88+
```python
7689
from vonage import Auth, Vonage
7790
from vonage_verify import VerifyRequest, SmsChannel
7891

@@ -91,70 +104,81 @@ verify_request = VerifyRequest(
91104
)
92105

93106
response = vonage_client.verify.start_verification(verify_request)
107+
```
94108

95-
This is explained in more detail in the blog post shared above. You can also find full, working examples in the Python Code Snippets repo here:
96-
https://github.com/Vonage/vonage-python-code-snippets
109+
This is explained in more detail in the blog post shared above. You can also find full, working examples [in the Python Code Snippets repo](https://github.com/Vonage/vonage-python-code-snippets).
110+
111+
### Getting the Objects You Need Into Your Namespace
97112

98-
Getting the Objects You Need Into Your Namespace
99113
If you’re working with e.g. the Voice API, if you know you’re likely to use many of the data models, you can import them all into your app’s namespace (making it easier for your autocomplete etc. to find them) with the `*` operator, e.g.
100114

115+
```python
101116
from vonage_voice import *
102117

103118
request = CreateCallRequest(...)
119+
```
104120

105121
It’s usually considered better practice to import just what you need, but using this method means the data models will all be available to you if you need to do some quick testing.
106-
How the SDK handles errors
122+
123+
## How the SDK handles errors
124+
107125
The Vonage Python SDK has various different classes of errors:
108126

109-
Some regular Python/package errors that can be raised during the course of SDK operation
110-
The top-level VonageError, that custom SDK errors inherit from
111-
Errors raised when using some packages, e.g. VerifyError
112-
Errors raised by the HTTP client
127+
- Some regular Python/package errors that can be raised during the course of SDK operation
128+
- The top-level `VonageError`, that custom SDK errors inherit from
129+
- Errors raised when using some packages, e.g. `VerifyError`
130+
- Errors raised by the HTTP client
113131

114132
It’s likely that when troubleshooting, you’ll especially see HTTP request errors, so let’s discuss these.
115-
HTTP Request Errors
133+
134+
### HTTP Request Errors
135+
116136
This is a class of errors raised when actually making the HTTP request or when receiving an HTTP response.
117137

118-
The higher-level error here is the HttpRequestError. There are other errors which are based on this and have the same properties, but different names that are more specific to the HTTP status code (https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) received from the Vonage server, e.g. an AuthenticationError or a NotFoundError.
138+
The high-level error here is the `HttpRequestError`. There are other errors which are based on this and have the same properties, but different names that are more specific to [the HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) received from the Vonage server, e.g. an `AuthenticationError` or a `NotFoundError`.
119139

120-
Each error of this type has properties that can be accessed when the error is caught. I.e. if you have a try-except block which catches an error, you can then access the error message and the response object which has additional information. This can be useful for debugging.
140+
Each error of this type has properties that can be accessed when the error is caught, i.e. if you have a try-except block which catches an error, you can then access the error message and the response object which has additional information. This can be useful for debugging.
121141

122142
To catch an error in this way, do this:
123143

124-
144+
```python
125145
try:
126146
vonage_client.call_vonage_api(...)
127147
except HttpRequestError as e:
128148
print(‘Request failed:’)
129149
print(e.message)
130150
print(e.response.text)
151+
```
152+
153+
You can access any information about the request or the response from the `e.response` object.
154+
155+
## Troubleshooting
131156

132-
You can access any information about the request or the response from the e.response object.
133-
Troubleshooting
134-
Viewing the last request and response
157+
### Viewing the last request and response
135158

136159
Whether or not an HTTP request was successful, you can access the last request and response sent by accessing the relevant HTTP client attributes like this:
137160

161+
```python
138162
vonage_client.http_client.last_request
139163
vonage_client.http_client.last_response
164+
```
140165

141166
For example, to see the last request body and headers sent by the SDK, you can do:
142167

168+
```python
143169
print(vonage_client.http_client.last_request.body)
144170
print(vonage_client.http_client.last_request.headers)
171+
```
145172

146-
Authentication errors
147-
148-
If the SDK returns an AuthenticationError, this is because the Vonage Server was not able to authenticate the SDK user. In this case, you should check the authentication details that were provided.
149-
150-
Useful Resources
151-
SDK on Github https://github.com/Vonage/vonage-python-sdk
152-
SDK on PyPI https://pypi.org/project/vonage/
153-
Python SDK introduction blog https://developer.vonage.com/en/blog/vonage-python-sdk-v4-is-now-live-#getting-started
154-
Migration guide from old to new SDK https://github.com/Vonage/vonage-python-sdk/blob/main/V3_TO_V4_SDK_MIGRATION_GUIDE.md
155-
Reach out to us on the #ask-devrel Slack channel if you have any questions.
173+
### Authentication errors
156174

175+
If the SDK returns an `AuthenticationError`, this is because the Vonage Server was not able to authenticate the SDK user. In this case, you should check the authentication details that were provided.
157176

177+
## Useful Resources
178+
- [Vonage Python SDK on Github](https://github.com/Vonage/vonage-python-sdk)
179+
- [Vonage Python SDK on PyPI](https://pypi.org/project/vonage/)
180+
- [Python SDK introduction blog](https://developer.vonage.com/en/blog/vonage-python-sdk-v4-is-now-live-#getting-started)
181+
- [Migration guide from old to new SDK](https://github.com/Vonage/vonage-python-sdk/blob/main/V3_TO_V4_SDK_MIGRATION_GUIDE.md)
158182

159183
## Request an Example
160184

0 commit comments

Comments
 (0)