| Name | spyip JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | |
| Summary | A simple IP lookup tool written in Python. |
| upload_time | 2024-01-30 18:25:35 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | The MIT License (MIT) Copyright (c) 2023 to present Md. Almas Ali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
ip
lookup
simple
utility
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1 align="center">SpyIP</h1>
<p align="center">
<a href="https://pepy.tech/project/spyip"><img src="https://static.pepy.tech/personalized-badge/spyip?period=total&units=none&left_color=grey&right_color=blue&left_text=Total%20Downloads"></a>
<a href="https://github.com/Almas-Ali/SpyIP/"><img src="https://img.shields.io/github/license/Almas-Ali/SpyIP?style=flat-square"></a>
<a href="https://wakatime.com/badge/user/168edf9f-71dc-49cc-bf77-592d9c9d4eed/project/018cbf9a-cecf-4ae8-ad59-a34b9eefb754"><img src="https://wakatime.com/badge/user/168edf9f-71dc-49cc-bf77-592d9c9d4eed/project/018cbf9a-cecf-4ae8-ad59-a34b9eefb754.svg" alt="wakatime"></a>
<a href="https://hits.seeyoufarm.com"><img src="https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FAlmas-Ali%2FSpyIP&count_bg=%2352B308&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false"/></a>
</p>
<p align="center">A simple IP lookup tool written in Python.
</p>
SpyIP uses <a href="https://ip-api.com/" target="_blank" title="IP-API">ip-api</a> API to trace IP addresses. SpyIP is type annotated, unit tested, PEP8 compliant, documented and optimized for performance.
## Features
- [x] Trace your own IP address
- [x] Trace your own DNS
- [x] Trace IP address by query
- [x] Trace batch IP address
- [x] Type annotated
- [x] Unit tested
- [x] PEP8 compliant
- [x] Documented
- [x] Optimized
## Installation
```bash
pip install spyip
```
## Usage
```python
from spyip import trace_me, trace_dns, trace_ip, trace_ip_batch
me = trace_me() # trace your own IP
print(me.json(indent=4)) # print as JSON with indent
dns = trace_dns() # trace your own DNS
print(dns.json()) # print as JSON
# trace by IP address (facebook.com)
ip = trace_ip(query="31.13.64.35")
print(ip.json()) # print as JSON
# set timeout
print(
trace_ip(
query="31.13.64.35",
timeout=5,
).json()
)
# batch trace by IP address (facebook.com, google.com, github.com, microsoft.com, ...)
batch = trace_ip_batch(
query_list=[
'31.13.64.35', # facebook.com
'142.250.193.206', # google.com
'20.205.243.166', # github.com
'20.236.44.162', # microsoft.com
],
)
print(batch) # print a list of IPResponse objects. (see below)
```
## Localization
Localized `city`, `regionName` and `country` can be translated to the following languages by passing `lang` argument to `trace_me`, `trace_ip` and `trace_ip_batch` functions. Default language is `en` (English). Here is the list of supported languages:
| lang (ISO 639) | description |
| -------------- | ------------------------------- |
| en | English (default) |
| de | Deutsch (German) |
| es | Español (Spanish) |
| pt-BR | Português - Brasil (Portuguese) |
| fr | Français (French) |
| ja | 日本語 (Japanese) |
| zh-CN | 中国 (Chinese) |
| ru | Русский (Russian) |
## Response objects
Response objects are `pydantic` base models. In `SpyIP` we have 2 response objects respectively:
<ol type="1">
<li>
<details>
<summary>
<code>IPResponse</code>: for single IP address query
</summary>
```python
@define
class IPResponse:
"""
Example response from API:
{
"status": "success",
"continent": "Asia",
"continentCode": "AS",
"country": "India",
"countryCode": "IN",
"region": "DL",
"regionName": "National Capital Territory of Delhi",
"city": "New Delhi",
"district": "",
"zip": "110001",
"lat": 28.6139,
"lon": 77.209,
"timezone": "Asia/Kolkata",
"offset": 19800,
"currency": "INR",
"isp": "Google LLC",
"org": "Google LLC",
"as": "AS15169 Google LLC",
"asname": "GOOGLE",
"mobile": false,
"proxy": false,
"hosting": true,
"query": "142.250.193.206",
}
"""
status: str = field(metadata={'description': 'Status of the request.'})
continent: str = field(metadata={'description': 'Continent name.'})
continentCode: str = field(metadata={'description': 'Continent code.'})
country: str = field(metadata={'description': 'Country name.'})
countryCode: str = field(metadata={'description': 'Country code.'})
region: str = field(metadata={'description': 'Region code.'})
regionName: str = field(metadata={'description': 'Region name.'})
city: str = field(metadata={'description': 'City name.'})
district: str = field(metadata={'description': 'District name.'})
zip_: str = field(metadata={'description': 'Zip code.'}, alias='zip')
lat: float = field(metadata={'description': 'Latitude.'})
lon: float = field(metadata={'description': 'Longitude.'})
timezone: str = field(metadata={'description': 'Timezone.'})
offset: int = field(metadata={'description': 'Offset.'})
currency: str = field(metadata={'description': 'Currency.'})
isp: str = field(metadata={'description': 'ISP name.'})
org: str = field(metadata={'description': 'Organization name.'})
as_: str = field(metadata={'description': 'AS number and name.'}, alias='as_')
asname: str = field(metadata={'description': 'AS name.'})
mobile: bool = field(metadata={'description': 'Mobile status.'})
proxy: bool = field(metadata={'description': 'Proxy status.'})
hosting: bool = field(metadata={'description': 'Hosting status.'})
query: str = field(metadata={'description': 'IP address.'})
```
</details>
</li>
<li>
<details>
<summary>
<code>DNSResponse</code>: for DNS query
</summary>
```python
@define
class DNSResponse:
"""
Example response from API:
"dns": {
"ip": "74.125.73.83",
"geo": "United States - Google"
}
"""
ip: str = field(metadata={'description': 'IP address.'})
geo: str = field(metadata={'description': 'Geo location.'})
```
</details>
</li>
</ol>
In batch query, `trace_ip_batch` returns a list of `IPResponse` objects. You can just iterate over the list and use as you need.
## Exceptions
`SpyIP` has 3 custom exceptions:
- `TooManyRequests` - raised when you exceed the API rate limit.
- `ConnectionTimeout` - raised when connection times out.
- `StatusError` - raised when API returns an error status.
## Tests
Test cases are located in `tests` directory. You can run tests with the following command:
```bash
python -m unittest discover -s tests
```
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. If you have any idea, suggestion or question, feel free to open an issue. Please make sure to update tests as appropriate.
## License
This project is licensed under the terms of the [MIT](LICENSE) license.
Raw data
{
"_id": null,
"home_page": "",
"name": "spyip",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "\"Md. Almas Ali\" <almaspr3@gmail.com>",
"keywords": "ip,lookup,simple,utility",
"author": "",
"author_email": "\"Md. Almas Ali\" <almaspr3@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2e/7e/a7dacb0b5891d7169aac8f7903c20309d031e4afdcb91869161ce2ee7fd0/spyip-0.2.0.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">SpyIP</h1>\n\n<p align=\"center\">\n<a href=\"https://pepy.tech/project/spyip\"><img src=\"https://static.pepy.tech/personalized-badge/spyip?period=total&units=none&left_color=grey&right_color=blue&left_text=Total%20Downloads\"></a>\n<a href=\"https://github.com/Almas-Ali/SpyIP/\"><img src=\"https://img.shields.io/github/license/Almas-Ali/SpyIP?style=flat-square\"></a>\n<a href=\"https://wakatime.com/badge/user/168edf9f-71dc-49cc-bf77-592d9c9d4eed/project/018cbf9a-cecf-4ae8-ad59-a34b9eefb754\"><img src=\"https://wakatime.com/badge/user/168edf9f-71dc-49cc-bf77-592d9c9d4eed/project/018cbf9a-cecf-4ae8-ad59-a34b9eefb754.svg\" alt=\"wakatime\"></a>\n<a href=\"https://hits.seeyoufarm.com\"><img src=\"https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FAlmas-Ali%2FSpyIP&count_bg=%2352B308&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false\"/></a>\n</p>\n\n<p align=\"center\">A simple IP lookup tool written in Python.\n</p>\n\nSpyIP uses <a href=\"https://ip-api.com/\" target=\"_blank\" title=\"IP-API\">ip-api</a> API to trace IP addresses. SpyIP is type annotated, unit tested, PEP8 compliant, documented and optimized for performance.\n\n## Features\n\n- [x] Trace your own IP address\n\n- [x] Trace your own DNS\n\n- [x] Trace IP address by query\n\n- [x] Trace batch IP address\n\n\n- [x] Type annotated\n\n- [x] Unit tested\n\n- [x] PEP8 compliant\n\n- [x] Documented\n\n- [x] Optimized\n\n\n## Installation\n\n```bash\npip install spyip\n```\n\n## Usage\n\n```python\nfrom spyip import trace_me, trace_dns, trace_ip, trace_ip_batch\n\n\nme = trace_me() # trace your own IP\nprint(me.json(indent=4)) # print as JSON with indent\n\n\ndns = trace_dns() # trace your own DNS\nprint(dns.json()) # print as JSON\n\n\n# trace by IP address (facebook.com)\nip = trace_ip(query=\"31.13.64.35\")\nprint(ip.json()) # print as JSON\n\n# set timeout\nprint(\n trace_ip(\n query=\"31.13.64.35\",\n timeout=5,\n ).json()\n)\n\n\n# batch trace by IP address (facebook.com, google.com, github.com, microsoft.com, ...)\nbatch = trace_ip_batch(\n query_list=[\n '31.13.64.35', # facebook.com\n '142.250.193.206', # google.com\n '20.205.243.166', # github.com\n '20.236.44.162', # microsoft.com\n ],\n)\nprint(batch) # print a list of IPResponse objects. (see below)\n```\n\n## Localization\n\nLocalized `city`, `regionName` and `country` can be translated to the following languages by passing `lang` argument to `trace_me`, `trace_ip` and `trace_ip_batch` functions. Default language is `en` (English). Here is the list of supported languages:\n\n| lang (ISO 639) | description |\n| -------------- | ------------------------------- |\n| en | English (default) |\n| de | Deutsch (German) |\n| es | Espa\u00f1ol (Spanish) |\n| pt-BR | Portugu\u00eas - Brasil (Portuguese) |\n| fr | Fran\u00e7ais (French) |\n| ja | \u65e5\u672c\u8a9e (Japanese) |\n| zh-CN | \u4e2d\u56fd (Chinese) |\n| ru | \u0420\u0443\u0441\u0441\u043a\u0438\u0439 (Russian) |\n\n## Response objects\n\nResponse objects are `pydantic` base models. In `SpyIP` we have 2 response objects respectively:\n\n<ol type=\"1\">\n<li>\n<details>\n<summary>\n<code>IPResponse</code>: for single IP address query\n</summary>\n\n```python\n@define\nclass IPResponse:\n \"\"\"\n Example response from API:\n\n {\n \"status\": \"success\",\n \"continent\": \"Asia\",\n \"continentCode\": \"AS\",\n \"country\": \"India\",\n \"countryCode\": \"IN\",\n \"region\": \"DL\",\n \"regionName\": \"National Capital Territory of Delhi\",\n \"city\": \"New Delhi\",\n \"district\": \"\",\n \"zip\": \"110001\",\n \"lat\": 28.6139,\n \"lon\": 77.209,\n \"timezone\": \"Asia/Kolkata\",\n \"offset\": 19800,\n \"currency\": \"INR\",\n \"isp\": \"Google LLC\",\n \"org\": \"Google LLC\",\n \"as\": \"AS15169 Google LLC\",\n \"asname\": \"GOOGLE\",\n \"mobile\": false,\n \"proxy\": false,\n \"hosting\": true,\n \"query\": \"142.250.193.206\",\n }\n \"\"\"\n\n status: str = field(metadata={'description': 'Status of the request.'})\n continent: str = field(metadata={'description': 'Continent name.'})\n continentCode: str = field(metadata={'description': 'Continent code.'})\n country: str = field(metadata={'description': 'Country name.'})\n countryCode: str = field(metadata={'description': 'Country code.'})\n region: str = field(metadata={'description': 'Region code.'})\n regionName: str = field(metadata={'description': 'Region name.'})\n city: str = field(metadata={'description': 'City name.'})\n district: str = field(metadata={'description': 'District name.'})\n zip_: str = field(metadata={'description': 'Zip code.'}, alias='zip')\n lat: float = field(metadata={'description': 'Latitude.'})\n lon: float = field(metadata={'description': 'Longitude.'})\n timezone: str = field(metadata={'description': 'Timezone.'})\n offset: int = field(metadata={'description': 'Offset.'})\n currency: str = field(metadata={'description': 'Currency.'})\n isp: str = field(metadata={'description': 'ISP name.'})\n org: str = field(metadata={'description': 'Organization name.'})\n as_: str = field(metadata={'description': 'AS number and name.'}, alias='as_')\n asname: str = field(metadata={'description': 'AS name.'})\n mobile: bool = field(metadata={'description': 'Mobile status.'})\n proxy: bool = field(metadata={'description': 'Proxy status.'})\n hosting: bool = field(metadata={'description': 'Hosting status.'})\n query: str = field(metadata={'description': 'IP address.'})\n```\n\n</details>\n</li>\n<li>\n<details>\n<summary>\n<code>DNSResponse</code>: for DNS query\n</summary>\n\n```python\n@define\nclass DNSResponse:\n \"\"\"\n Example response from API:\n \"dns\": {\n \"ip\": \"74.125.73.83\",\n \"geo\": \"United States - Google\"\n }\n \"\"\"\n\n ip: str = field(metadata={'description': 'IP address.'})\n geo: str = field(metadata={'description': 'Geo location.'})\n```\n\n</details>\n</li>\n</ol>\n\nIn batch query, `trace_ip_batch` returns a list of `IPResponse` objects. You can just iterate over the list and use as you need.\n\n## Exceptions\n\n`SpyIP` has 3 custom exceptions:\n\n- `TooManyRequests` - raised when you exceed the API rate limit.\n- `ConnectionTimeout` - raised when connection times out.\n- `StatusError` - raised when API returns an error status.\n\n## Tests\n\nTest cases are located in `tests` directory. You can run tests with the following command:\n\n```bash\npython -m unittest discover -s tests\n```\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. If you have any idea, suggestion or question, feel free to open an issue. Please make sure to update tests as appropriate.\n\n## License\n\nThis project is licensed under the terms of the [MIT](LICENSE) license.\n",
"bugtrack_url": null,
"license": "The MIT License (MIT) Copyright (c) 2023 to present Md. Almas Ali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "A simple IP lookup tool written in Python.",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/Almas-Ali/SpyIP/issues",
"Documentation": "https://github.com/Almas-Ali/SpyIP#readme",
"Homepage": "https://github.com/Almas-Ali/SpyIP",
"Repository": "https://github.com/Almas-Ali/spyip"
},
"split_keywords": [
"ip",
"lookup",
"simple",
"utility"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2d08fb0458553e182965b1777c6d429fb95290b0424dbbd2191284b85e175482",
"md5": "7be30ba5d1cdcc5d842926d1e5d4f21c",
"sha256": "607435cfa550ca3fa3989bc252311227f0dac04a6e136e0b6b177a70c7817b36"
},
"downloads": -1,
"filename": "spyip-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7be30ba5d1cdcc5d842926d1e5d4f21c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8838,
"upload_time": "2024-01-30T18:25:33",
"upload_time_iso_8601": "2024-01-30T18:25:33.981649Z",
"url": "https://files.pythonhosted.org/packages/2d/08/fb0458553e182965b1777c6d429fb95290b0424dbbd2191284b85e175482/spyip-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2e7ea7dacb0b5891d7169aac8f7903c20309d031e4afdcb91869161ce2ee7fd0",
"md5": "d137d954341bf75d894f9487e218f77a",
"sha256": "bbd3aa5ee23b7d6ecb6dd15f41f525b59d75f052bad664fa94aa6ac80a736db3"
},
"downloads": -1,
"filename": "spyip-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "d137d954341bf75d894f9487e218f77a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7668,
"upload_time": "2024-01-30T18:25:35",
"upload_time_iso_8601": "2024-01-30T18:25:35.090556Z",
"url": "https://files.pythonhosted.org/packages/2e/7e/a7dacb0b5891d7169aac8f7903c20309d031e4afdcb91869161ce2ee7fd0/spyip-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-30 18:25:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Almas-Ali",
"github_project": "SpyIP",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "spyip"
}
