Skip to main content

A simple IP lookup tool written in Python with concurrency support.

Project description

SpyIP

A simple IP lookup tool written in Python with concurrency support.

wakatime

Table of Contents

Introduction

SpyIP uses ip-api API to trace IP addresses. SpyIP is default synchronous and supports asynchronous operations. It is type annotated, PEP8 compliant, documented and unit tested.

Features

  • Trace your own IP address

  • Trace your own DNS

  • Trace IP address by query

  • Trace batch IP address

  • Asynchronous supported

  • Synchronous by default

  • Type annotated

  • Unit tested

  • PEP8 compliant

  • Documented

  • Optimized

Installation

pip install spyip

Usage

Default synchronous use case for normal and easy to use.

from spyip import trace_me, trace_dns, trace_ip, trace_ip_batch # default synchronous functions


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)

Advance asynchronous way to boost performance. Just a simple example to show how to use asyncio with SpyIP.

import asyncio

from spyip.backends.asynchronous import trace_me, trace_dns, trace_ip, trace_ip_batch # asynchronous functions


async def spy_trace_me():
    result = await trace_me()
    print(result)


async def spy_trace_dns():
    result = await trace_dns()
    print(result)


async def spy_trace_ip():
    result = await trace_ip(query="31.13.64.35")
    print(result)


async def spy_trace_ip_batch():
    result = await 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(result)


async def main():
    '''Load all tasks'''
    await spy_trace_me()
    await spy_trace_dns()
    await spy_trace_ip()
    await spy_trace_ip_batch()

asyncio.run(main()) # run the main function

Localizations

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)

Responses

Response objects are attrs for defining Response models. In SpyIP we have 2 response objects respectively:

  1. IPResponse: for single IP address query
    @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.'})
    
  2. DNSResponse: for DNS query
    @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.'})
    

In batch query, trace_ip_batch returns a list of IPResponse objects (List[IPResponse]). 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 commands:

# run all tests in tests directory at once
python -m unittest discover -s tests

# run asynchronous tests
python tests/test_asynchronous.py

# run synchronous tests
python tests/test_synchronous.py

Average Time Comparisons:

Types Tests Time
Total tests 12 6.188s
Asynchronous 6 2.751s
Synchronous 6 2.968s

Note: This time comparison is based on network performance and hardware capabilities. I am using a very old low-configuration laptop and running on Python 3.11.7. This result may vary depending on your system resources.

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

spyip-0.3.0.tar.gz (9.7 kB view details)

Uploaded Source

Built Distribution

spyip-0.3.0-py3-none-any.whl (11.4 kB view details)

Uploaded Python 3

File details

Details for the file spyip-0.3.0.tar.gz.

File metadata

  • Download URL: spyip-0.3.0.tar.gz
  • Upload date:
  • Size: 9.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.18

File hashes

Hashes for spyip-0.3.0.tar.gz
Algorithm Hash digest
SHA256 d6d6f3723ebec65ad15dc8b6c6dd1461d1829631ff1ea18f58ba7801a834cba7
MD5 4a6db9c84ad7fbe130f23e4fef75505a
BLAKE2b-256 89a67b8b21d89d38fe3d565cd83d90727209ab17cb57a9d7cd6c03d270ba29c2

See more details on using hashes here.

File details

Details for the file spyip-0.3.0-py3-none-any.whl.

File metadata

  • Download URL: spyip-0.3.0-py3-none-any.whl
  • Upload date:
  • Size: 11.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.18

File hashes

Hashes for spyip-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 d49a4470c16f5729f96c04482287330e2435539b176b70eb398c7e6577c15e98
MD5 177baceec07b925e7660e4d65aba8e51
BLAKE2b-256 d4ff3e503fb65ea0c28ff400518d2f58d316dc30293f54ddcd5b9275494e08ef

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page