or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

async-handlers.mddata-utilities.mdindex.mdsync-handlers.md
tile.json

tessl/pypi-ipinfo

Official Python library for IPInfo IP address geolocation and data lookups

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/ipinfo@5.2.x

To install, run

npx @tessl/cli install tessl/pypi-ipinfo@5.2.0

index.mddocs/

IPInfo Python Client Library

A comprehensive Python client library for the IPinfo.io IP address API, enabling developers to perform IP geolocation lookups and retrieve detailed information about IP addresses including geographic location, ASN details, firmographics data, and carrier information.

Package Information

  • Package Name: ipinfo
  • Language: Python
  • Installation: pip install ipinfo

Core Imports

import ipinfo

For direct class access:

from ipinfo import Handler, HandlerLite, AsyncHandler, AsyncHandlerLite
from ipinfo.details import Details
from ipinfo.exceptions import RequestQuotaExceededError, TimeoutExceededError
from ipinfo.error import APIError

Basic Usage

import ipinfo

# Initialize handler with API token
access_token = '123456789abc'
handler = ipinfo.getHandler(access_token)

# Get details for specific IP
ip_address = '216.239.36.21'
details = handler.getDetails(ip_address)

# Access individual fields
print(details.city)        # 'Mountain View'
print(details.country)     # 'US'
print(details.loc)         # '37.3861,-122.0840'
print(details.latitude)    # '37.3861'
print(details.longitude)   # '-122.0840'

# Get all details as dictionary
print(details.all)

# Get details for current IP (omit ip_address parameter)
my_details = handler.getDetails()

Architecture

The library provides four main handler classes organized by API type and synchronization model:

  • Handler/HandlerLite: Synchronous clients for Core API and Lite API respectively
  • AsyncHandler/AsyncHandlerLite: Asynchronous clients for Core API and Lite API respectively
  • Details: Response object providing attribute-based access to IP information
  • Cache System: Pluggable caching interface with default LRU implementation
  • Utilities: Helper functions for formatting, validation, and configuration

All handlers support comprehensive configuration including custom caching, timeouts, headers, and internationalization options.

Capabilities

Synchronous Handlers

Primary synchronous API clients for IP lookups supporting both Core API and Lite API endpoints with comprehensive caching, batch operations, and extensive configuration options.

def getHandler(access_token=None, **kwargs): ...
def getHandlerLite(access_token=None, **kwargs): ...

class Handler:
    def __init__(self, access_token=None, **kwargs): ...
    def getDetails(self, ip_address=None, timeout=None): ...
    def getBatchDetails(self, ip_addresses, batch_size=None, timeout_per_batch=5, timeout_total=None, raise_on_fail=True): ...
    def getBatchDetailsIter(self, ip_addresses, batch_size=None, raise_on_fail=True): ...
    def getMap(self, ips): ...

class HandlerLite:
    def __init__(self, access_token=None, **kwargs): ...
    def getDetails(self, ip_address=None, timeout=None): ...

Synchronous Handlers

Asynchronous Handlers

Asynchronous API clients providing concurrent IP lookups with aiohttp-based implementation, supporting both Core API and Lite API endpoints with advanced timeout controls and batch processing.

def getHandlerAsync(access_token=None, **kwargs): ...
def getHandlerAsyncLite(access_token=None, **kwargs): ...

class AsyncHandler:
    def __init__(self, access_token=None, **kwargs): ...
    async def init(self): ...
    async def deinit(self): ...
    async def getDetails(self, ip_address=None, timeout=None): ...
    async def getBatchDetails(self, ip_addresses, batch_size=None, timeout_per_batch=5, timeout_total=None, raise_on_fail=True): ...
    async def getBatchDetailsIter(self, ip_addresses, batch_size=None, raise_on_fail=True): ...

class AsyncHandlerLite:
    def __init__(self, access_token=None, **kwargs): ...
    async def init(self): ...
    async def deinit(self): ...
    async def getDetails(self, ip_address=None, timeout=None): ...

Asynchronous Handlers

Data Structures and Utilities

Response objects, caching system, exception handling, and utility functions for data formatting, validation, and configuration management.

class Details:
    def __init__(self, details): ...
    def __getattr__(self, attr): ...
    @property
    def all(self): ...

class RequestQuotaExceededError(Exception): ...
class TimeoutExceededError(Exception): ...
class APIError(Exception):
    def __init__(self, error_code, error_json): ...

from ipinfo.cache.interface import CacheInterface
from ipinfo.cache.default import DefaultCache

Data Structures and Utilities

Types

# Configuration options for handlers
HandlerKwargs = {
    'countries': dict,           # Custom country name mappings
    'eu_countries': list,        # Custom EU country list
    'countries_flags': dict,     # Custom country flag mappings
    'countries_currencies': dict, # Custom currency mappings
    'continent': dict,           # Custom continent mappings
    'request_options': dict,     # HTTP request configuration
    'cache_options': dict,       # Cache configuration
    'cache': CacheInterface,     # Custom cache implementation
    'headers': dict             # Custom HTTP headers
}

# Response data structure
IPDetails = {
    'ip': str,
    'hostname': str,
    'city': str,
    'region': str,
    'country': str,
    'loc': str,           # "latitude,longitude"
    'org': str,
    'postal': str,
    'timezone': str,
    'country_name': str,  # Added by library
    'latitude': str,      # Added by library
    'longitude': str,     # Added by library
    'isEU': bool,        # Added by library
    'country_flag': dict, # Added by library
    'country_currency': dict, # Added by library
    'continent': dict     # Added by library
}