Skip to content

Commit 8c5b806

Browse files
maxkahanmaxkahan
committed
start adding number insight
1 parent b304344 commit 8c5b806

File tree

18 files changed

+323
-0
lines changed

18 files changed

+323
-0
lines changed

‎number_insight/BUILD‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
resource(name='pyproject', source='pyproject.toml')
2+
file(name='readme', source='README.md')
3+
4+
files(sources=['tests/data/*'])
5+
6+
python_distribution(
7+
name='vonage-number-insight',
8+
dependencies=[
9+
':pyproject',
10+
':readme',
11+
'number_insight/src/vonage_number_insight',
12+
],
13+
provides=python_artifact(),
14+
generate_setup=False,
15+
repositories=['@pypi'],
16+
)

‎number_insight/CHANGES.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# 1.0.0
2+
- Initial upload

‎number_insight/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Vonage Number Insight Package
2+
3+
This package contains the code to use [Vonage's Number Insight API](https://developer.vonage.com/en/number-insight/overview) in Python. This package includes methods to get information about phone numbers. It has 3 levels of insight, basic, standard, and advanced.
4+
5+
## Usage
6+
7+
It is recommended to use this as part of the main `vonage` package. The examples below assume you've created an instance of the `vonage.Vonage` class called `vonage_client`.
8+
9+
### Make a Basic Number Insight Request

‎number_insight/pyproject.toml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
[project]
2+
name = 'vonage-number-insight'
3+
version = '1.0.0'
4+
description = 'Vonage Number Insight package'
5+
readme = "README.md"
6+
authors = [{ name = "Vonage", email = "devrel@vonage.com" }]
7+
requires-python = ">=3.8"
8+
dependencies = [
9+
"vonage-http-client>=1.3.0",
10+
"vonage-utils>=1.1.0",
11+
"pydantic>=2.6.1",
12+
]
13+
classifiers = [
14+
"Programming Language :: Python",
15+
"Programming Language :: Python :: 3",
16+
"Programming Language :: Python :: 3.8",
17+
"Programming Language :: Python :: 3.9",
18+
"Programming Language :: Python :: 3.10",
19+
"Programming Language :: Python :: 3.11",
20+
"Programming Language :: Python :: 3.12",
21+
"License :: OSI Approved :: Apache Software License",
22+
]
23+
24+
[project.urls]
25+
homepage = "https://github.com/Vonage/vonage-python-sdk"
26+
27+
[build-system]
28+
requires = ["setuptools>=61.0", "wheel"]
29+
build-backend = "setuptools.build_meta"

‎number_insight/src/vonage_number_insight/BUILD‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
python_sources()

‎number_insight/src/vonage_number_insight/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
from .number_insight import NumberInsight
2+
3+
__all__ = ['NumberInsight']

‎number_insight/src/vonage_number_insight/enums.py‎

Whitespace-only changes.

‎number_insight/src/vonage_number_insight/errors.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
from vonage_utils.errors import VonageError
2+
3+
4+
class NumberInsightError(VonageError):
5+
"""Indicates an error when using the Vonage Number Insight API."""

‎number_insight/src/vonage_number_insight/number_insight.py‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
from pydantic import validate_call
2+
from vonage_http_client.http_client import HttpClient
3+
4+
from .errors import NumberInsightError
5+
from .requests import (
6+
AdvancedAsyncInsightRequest,
7+
AdvancedSyncInsightRequest,
8+
BasicInsightRequest,
9+
StandardInsightRequest,
10+
)
11+
from .responses import (
12+
AdvancedAsyncInsightResponse,
13+
AdvancedSyncInsightResponse,
14+
BasicInsightResponse,
15+
StandardInsightResponse,
16+
)
17+
18+
19+
class NumberInsight:
20+
"""Calls Vonage's Number Insight API."""
21+
22+
def __init__(self, http_client: HttpClient) -> None:
23+
self._http_client = http_client
24+
self._auth_type = 'body'
25+
26+
@property
27+
def http_client(self) -> HttpClient:
28+
"""The HTTP client used to make requests to the Verify V2 API.
29+
30+
Returns:
31+
HttpClient: The HTTP client used to make requests to the Verify V2 API.
32+
"""
33+
return self._http_client
34+
35+
@validate_call
36+
def basic_number_insight(self, options: BasicInsightRequest) -> BasicInsightResponse:
37+
"""Get basic number insight information about a phone number.
38+
39+
Args:
40+
Options (BasicInsightRequest): The options for the request. The `number` paramerter
41+
is required, and the `country_code` parameter is optional.
42+
43+
Returns:
44+
BasicInsightResponse: The response object containing the basic number insight
45+
information about the phone number.
46+
"""
47+
response = self._http_client.get(
48+
self._http_client.api_host,
49+
'/ni/basic/json',
50+
params=options.model_dump(exclude_none=True),
51+
auth_type=self._auth_type,
52+
)
53+
self._check_for_error(response)
54+
55+
return BasicInsightResponse(**response)
56+
57+
@validate_call
58+
def standard_number_insight(
59+
self, options: StandardInsightRequest
60+
) -> StandardInsightResponse:
61+
"""Get standard number insight information about a phone number.
62+
63+
Args:
64+
Options (StandardInsightRequest): The options for the request. The `number` paramerter
65+
is required, and the `country_code` and `cnam` parameters are optional.
66+
67+
Returns:
68+
StandardInsightResponse: The response object containing the standard number insight
69+
information about the phone number.
70+
"""
71+
response = self._http_client.get(
72+
self._http_client.api_host,
73+
'/ni/standard/json',
74+
params=options.model_dump(exclude_none=True),
75+
auth_type=self._auth_type,
76+
)
77+
self._check_for_error(response)
78+
79+
return StandardInsightResponse(**response)
80+
81+
@validate_call
82+
def advanced_async_number_insight(
83+
self, options: AdvancedAsyncInsightRequest
84+
) -> AdvancedAsyncInsightResponse:
85+
"""Get advanced number insight information about a phone number asynchronously.
86+
87+
Args:
88+
Options (AdvancedAsyncInsightRequest): The options for the request. You must provide values
89+
for the `callback` and `number` parameters. The `country_code` and `cnam` parameters
90+
are optional.
91+
92+
Returns:
93+
AdvancedAsyncInsightResponse: The response object containing the advanced number insight
94+
information about the phone number.
95+
"""
96+
response = self._http_client.get(
97+
self._http_client.api_host,
98+
'/ni/advanced/async/json',
99+
params=options.model_dump(exclude_none=True),
100+
auth_type=self._auth_type,
101+
)
102+
103+
return AdvancedAsyncInsightResponse(**response)
104+
105+
@validate_call
106+
def advanced_sync_number_insight(
107+
self, options: AdvancedSyncInsightRequest
108+
) -> AdvancedSyncInsightResponse:
109+
"""Get advanced number insight information about a phone number synchronously.
110+
111+
Args:
112+
Options (AdvancedSyncInsightRequest): The options for the request. The `number` parameter
113+
is required, and the `country_code`, `cnam`, and `real_time_data` parameters are optional.
114+
115+
Returns:
116+
AdvancedSyncInsightResponse: The response object containing the advanced number insight
117+
information about the phone number.
118+
"""
119+
response = self._http_client.get(
120+
self._http_client.api_host,
121+
'/ni/advanced/json',
122+
params=options.model_dump(exclude_none=True),
123+
auth_type=self._auth_type,
124+
)
125+
126+
return AdvancedSyncInsightResponse(**response)
127+
128+
def _check_for_error(self, response: dict) -> None:
129+
"""Check for an error in the response from the Number Insight API.
130+
131+
Args:
132+
response (dict): The response from the Number Insight API.
133+
134+
Raises:
135+
NumberInsightError: If the response contains an error.
136+
"""
137+
if response['status'] != 0:
138+
error_message = f'Error with the following details: {response}'
139+
raise NumberInsightError(error_message)

‎number_insight/src/vonage_number_insight/requests.py‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
from typing import Optional
2+
3+
from pydantic import BaseModel
4+
from vonage_utils.types import PhoneNumber
5+
6+
7+
class BasicInsightRequest(BaseModel):
8+
number: PhoneNumber
9+
country: Optional[str] = None
10+
11+
12+
class StandardInsightRequest(BasicInsightRequest):
13+
cnam: Optional[bool] = None
14+
15+
16+
class AdvancedAsyncInsightRequest(StandardInsightRequest):
17+
callback: str
18+
19+
20+
class AdvancedSyncInsightRequest(StandardInsightRequest):
21+
real_time_data: Optional[bool] = None

0 commit comments

Comments
 (0)