geofeed-tools

geofeed-tools is a Python library and CLI for working with RFC 8805 geofeeds. It supports parsing, validation, normalization, querying, and summary reporting for local files and remote HTTP(S) sources.

geofeed-tools

Basic Overview

Validate geofeed quality and RFC 8805 compliance
Normalize records - ensure there are no duplicates, invalid prefixes (eg. host bits set), case is correct
Query geofeeds by searching for IPs or prefixes
Discover published geofeeds for an IP or prefix via RDAP and query the discovered feed
Use as either a Python API or a CLI
CLI hook command available for use in version control hooks or CI/CD tests

Installation

To install the core library with only the API available:

uv pip install geofeed-tools

To install the full library including the CLI:

uv pip install 'geofeed-tools[cli]'

To install the library with async HTTP support for AsyncGeoFeed URL loading:

uv pip install 'geofeed-tools[async]'

Install development dependencies:

uv pip install 'geofeed-tools[dev]'

Docker

If Docker is available, you can run the CLI without installing Python or package dependencies on the host.

Published images:

GHCR: ghcr.io/python-modules/geofeed-tools
Docker Hub: pythonmodules/geofeed-tools
Floating tags: python3, python3.11, python3.12, python3.13
latest tracks the python3 build

The containers entry point is the CLI; run by simpling providing the command/arguments. As an example:

docker run --rm pythonmodules/geofeed-tools:latest doctor 192.0.2.0

Python API

Quick Start

from geofeed_tools import GeoFeed

geofeed = GeoFeed("https://api.cloudflare.com/local-ip-ranges.csv")

# Parse into GeofeedRecord objects
records = geofeed.parse()

# Parse into JSON
json_records = geofeed.parse(output="json")

# Validate with optional extra aggregation checks enabled
report = geofeed.validate(check_aggregation=True)

# Normalize into canonical CSV output
normalized_csv = geofeed.normalize(output="csv")

# Longest-prefix query for an IP address
match_ip = geofeed.query("192.0.2.1")

# Query a prefix and include all matching sub-prefixes
all_matches = geofeed.query("192.0.2.0/24", return_all=True, include_longer=True)

# Discover the published geofeed for an address or prefix via RDAP
diagnosis = GeoFeed.doctor("31.133.128.1")

# Discover the published geofeed and return only query matches
lookup = GeoFeed.lookup("31.133.128.1")

# Build a high-level summary
summary = geofeed.info()

Async quick start:

from geofeed_tools import AsyncGeoFeed

geofeed = AsyncGeoFeed("https://api.cloudflare.com/local-ip-ranges.csv")

# Methods mirror GeoFeed, but are awaitable
records = await geofeed.parse()
report = await geofeed.validate(check_aggregation=True)
summary = await geofeed.info()

# RDAP-based discovery does not require constructing an instance first
diagnosis = await AsyncGeoFeed.doctor("31.133.128.1")
lookup = await AsyncGeoFeed.lookup("31.133.128.1")

# Or eagerly load first with the async factory
preloaded = await AsyncGeoFeed.from_source("https://api.cloudflare.com/local-ip-ranges.csv")

Public Imports

The top-level package exports the main API object plus the public dataclasses:

from geofeed_tools import (
  AsyncGeoFeed,
  DoctorLookup,
  DoctorResult,
  GeoFeedDiscoveryError,
	GeoFeed,
	GeoFeedInfo,
	GeofeedRecord,
	QueryResult,
	ValidationIssue,
	ValidationReport,
)

`AsyncGeoFeed`

AsyncGeoFeed is the native async counterpart to GeoFeed for library users who want to integrate geofeed processing into an asyncio application.

Constructor:

AsyncGeoFeed(source: str, *, cache_query_index: bool = True)

Async factory for eager loading:

await AsyncGeoFeed.from_source(
    source: str,
    *,
    cache_query_index: bool = True,
) -> AsyncGeoFeed

Available async methods:

await reload() -> None
await parse(...) -> list[GeofeedRecord] | str
await validate(...) -> ValidationReport | str
await normalize(...) -> list[GeofeedRecord] | str
await query(...) -> QueryResult | str
await AsyncGeoFeed.doctor(...) -> DoctorResult | str
await AsyncGeoFeed.lookup(...) -> QueryResult | str
await info(...) -> GeoFeedInfo | str

Behavior notes:

AsyncGeoFeed accepts the same flags and output modes as GeoFeed for parse(), validate(), normalize(), query(), and info().
cache_query_index=False disables per-instance query-index caching for repeated await query(...) calls.
AsyncGeoFeed.doctor() is a static async helper that performs RDAP discovery, fetches the published geofeed, and returns structured lookup metadata together with the geofeed matches.
AsyncGeoFeed.lookup() is the async counterpart to GeoFeed.lookup(): it performs the same RDAP discovery flow but returns only QueryResult data.
Local file loading is performed asynchronously via thread offloading.
Remote URL loading uses async HTTP and requires the geofeed-tools[async] extra.
Parsing, validation, normalization, querying, and info generation run off the event loop in worker threads so library consumers can use the API without blocking the loop on large feeds.

`GeoFeed`

Constructor

GeoFeed(
    source: str,
    *,
    auto_load: bool = True,
    cache_query_index: bool = True,
)

Create a geofeed wrapper around a local file path or an HTTP(S) URL.

Argument	Type	Default	Meaning
`source`	`str`	required	Local file path or remote HTTP(S) geofeed URL.
`auto_load`	`bool`	`True`	Load the source immediately. If `False`, the first call to `parse()`, `validate()`, `normalize()`, `query()`, `info()`, or `reload()` performs the load.
`cache_query_index`	`bool`	`True`	Cache the parsed query index on the instance between `query()` calls. Set to `False` for one-shot usage patterns where index reuse is not helpful.

After loading, the object keeps these attributes populated:

source: original path or URL
raw: raw bytes fetched from the source
content_type: HTTP Content-Type header for URL sources, otherwise None
text: decoded UTF-8 text with any UTF-8 BOM stripped during load
query-index cache state used by query() when cache_query_index=True

`reload()`

reload() -> None

Re-read a local file or re-fetch a remote URL and refresh raw, content_type, and text.

`parse()`

parse(
	*,
	include_validation: bool = True,
	normalize: bool = False,
	output: str = "objects",
) -> list[GeofeedRecord] | str

Parse the current source into geofeed records.

Argument	Type	Default	Meaning
`include_validation`	`bool`	`True`	Annotate each returned record with `valid` and `validation_messages` based on validation errors.
`normalize`	`bool`	`False`	Normalize the feed first, then return normalized records instead of the original parsed rows.
`output`	`str`	`"objects"`	One of `"objects"`, `"json"`, or `"csv"`. Any other value raises `ValueError`.

Return modes:

output="objects": returns list[GeofeedRecord]
output="json": returns a JSON array string
output="csv": returns CSV text

Notes:

Malformed CSV rows and rows with a missing prefix are skipped during parsing.
Rows with invalid prefixes are still returned by parse(). With include_validation=True, those records are marked invalid and include the corresponding validation messages.
For output="json" and output="csv", include_validation=True includes the valid state and validation messages in the serialized output.
With normalize=True, records are rebuilt from normalized output. That is useful for producing clean data, but it does not preserve original source line numbers. If you need original per-line validation context, use normalize=False.

`validate()`

validate(
	*,
	check_sort: bool = True,
	check_content_type: bool = True,
	check_aggregation: bool = False,
	output: str = "objects",
) -> ValidationReport | str

Validate the current source and return a structured report.

Argument	Type	Default	Meaning
`check_sort`	`bool`	`True`	Check whether records are emitted in sorted prefix order.
`check_content_type`	`bool`	`True`	For HTTP(S) sources, warn when the response `Content-Type` is not `text/csv`.
`check_aggregation`	`bool`	`False`	Warn when multiple prefixes with identical geo metadata could be safely aggregated.
`output`	`str`	`"objects"`	One of `"objects"`, `"json"`, or `"text"`. Any other value raises `ValueError`.

Return modes:

output="objects": returns ValidationReport
output="json": returns a JSON object string
output="text": returns a human-readable text report

`normalize()`

normalize(
	*,
	uppercase: bool = True,
	sort: bool = True,
	aggregate: bool = True,
	dedupe: bool = True,
	fix_host_bits: bool = True,
	output: str = "objects",
) -> list[GeofeedRecord] | str

Normalize records into a cleaner, more canonical form.

Argument	Type	Default	Meaning
`uppercase`	`bool`	`True`	Uppercase country and region fields.
`sort`	`bool`	`True`	Sort normalized output by IP family and network value.
`aggregate`	`bool`	`True`	Collapse prefixes that share identical geo metadata into larger prefixes when possible.
`dedupe`	`bool`	`True`	Remove exact duplicate `prefix + metadata` rows when `aggregate=False`.
`fix_host_bits`	`bool`	`True`	Accept prefixes with host bits set and coerce them to the containing network. If `False`, such rows are skipped.
`output`	`str`	`"objects"`	One of `"objects"`, `"json"`, or `"csv"`. Any other value raises `ValueError`.

Return modes:

output="objects": returns list[GeofeedRecord]
output="json": returns a JSON array string
output="csv": returns CSV text

Notes:

aggregate=True already removes exact duplicate networks within each metadata group, so dedupe only has an effect when aggregate=False.
Normalized records are synthetic output rows. They do not preserve original line numbers, raw input lines, or validation metadata.

`query()`

query(
	query: str,
	*,
	return_all: bool = False,
	include_longer: bool = False,
	output: str = "objects",
) -> QueryResult | str

Query the current geofeed with an IP address or CIDR prefix.

Argument	Type	Default	Meaning
`query`	`str`	required	IP address or CIDR prefix to look up.
`return_all`	`bool`	`False`	Return every match instead of only the most specific one.
`include_longer`	`bool`	`False`	When the query is a prefix, include more-specific records that are contained inside that prefix.
`output`	`str`	`"objects"`	One of `"objects"`, `"json"`, or `"csv"`. Any other value raises `ValueError`.

Return modes:

output="objects": returns QueryResult
output="json": returns a JSON object string
output="csv": returns CSV text containing matching records only

Matching behavior:

For IP queries, the default behavior is effectively longest-prefix match.
For prefix queries, the default behavior returns the most specific covering prefix.
return_all=True returns every match sorted from most specific to least specific.
include_longer=True also returns more-specific prefixes contained by the queried network.

`doctor()`

GeoFeed.doctor(
  query: str,
  *,
  return_all: bool = False,
  include_longer: bool = False,
  rdap_method: str = "rdap.org",
  output: str = "objects",
) -> DoctorResult | str

Discover a published geofeed for an IP address or prefix via RDAP, fetch that geofeed, and query it.

Argument	Type	Default	Meaning
`query`	`str`	required	IP address or CIDR prefix to diagnose.
`return_all`	`bool`	`False`	Return every matching geofeed row instead of only the most specific one.
`include_longer`	`bool`	`False`	When the query is a prefix, include more-specific rows contained inside that prefix.
`rdap_method`	`str`	`"rdap.org"`	RDAP lookup method: `"rdap.org"` for fast gateway lookups or `"iana-bootstrap"` to resolve the RIR service directly from IANA bootstrap data.
`output`	`str`	`"objects"`	One of `"objects"`, `"json"`, or `"text"`. Any other value raises `ValueError`.

Return modes:

output="objects": returns DoctorResult
output="json": returns a JSON object string
output="text": returns a human-readable text report with lookup trace and matches

Behavior notes:

GeoFeed.doctor() is a static helper. It does not use a preloaded GeoFeed instance or require a source argument.
IP input is queried against RDAP directly. Prefix input is resolved via the prefix network address because RDAP IP lookups are address-based.
Discovery supports direct RDAP geofeed links as well as remark/comment references such as Geofeed: https://example.com/geofeed.csv.
If the most specific RDAP object does not publish a geofeed reference but exposes rdap-up, the lookup walks parent objects until the most specific published geofeed reference is found.
Only geofeed rows covered by the referring RDAP object range are considered during the final lookup.
rdap_method="rdap.org" is the default because it avoids downloading bootstrap data for each process start. rdap_method="iana-bootstrap" uses IANA bootstrap files to select the registry endpoint directly, which is useful when you do not want to rely on rdap.org.

`lookup()`

GeoFeed.lookup(
  query: str,
  *,
  return_all: bool = False,
  include_longer: bool = False,
  rdap_method: str = "rdap.org",
  output: str = "objects",
) -> QueryResult | str

Discover a published geofeed for an IP address or prefix via RDAP, fetch that geofeed, and return only the query result.

Argument	Type	Default	Meaning
`query`	`str`	required	IP address or CIDR prefix to look up.
`return_all`	`bool`	`False`	Return every matching geofeed row instead of only the most specific one.
`include_longer`	`bool`	`False`	When the query is a prefix, include more-specific rows contained inside that prefix.
`rdap_method`	`str`	`"rdap.org"`	RDAP lookup method: `"rdap.org"` for fast gateway lookups or `"iana-bootstrap"` to resolve the RIR service directly from IANA bootstrap data.
`output`	`str`	`"objects"`	One of `"objects"`, `"json"`, or `"csv"`. Any other value raises `ValueError`.

Return modes:

output="objects": returns QueryResult
output="json": returns a JSON object string
output="csv": returns CSV text containing matching records only

Behavior notes:

GeoFeed.lookup() is a static helper. It does not require a preloaded GeoFeed instance or a source argument.
It uses the same RDAP discovery rules as GeoFeed.doctor() but strips the RDAP metadata from the return value.
If no published geofeed URL is found, it raises GeoFeedDiscoveryError.

`info()`

info(*, output: str = "objects") -> GeoFeedInfo | str

Compute summary statistics for the current geofeed.

Argument	Type	Default	Meaning
`output`	`str`	`"objects"`	One of `"objects"` or `"json"`. Any other value raises `ValueError`.

Return modes:

output="objects": returns GeoFeedInfo
output="json": returns a JSON object string

Public Data Models

`GeofeedRecord`

Represents a single geofeed row.

Field	Type	Meaning
`prefix`	`str`	Network prefix from the feed.
`country`	`str`	ISO 3166-1 alpha-2 country code when present.
`region`	`str`	Region or subdivision field.
`city`	`str`	City field.
`postal_code`	`str`	Postal code field.
`line`	`int`	Source line number when the record came directly from parsing. Normalized records may use `0`.
`raw_line`	`str	None`
`valid`	`bool`	`True` when no validation errors were attached to the record.
`validation_messages`	`tuple[str, ...]`	Record-level validation error messages.

Helper:

record.as_dict(include_validation: bool = True, include_raw_line: bool = False) -> dict[str, object]

`ValidationIssue`

Represents one validation error or warning.

Field	Type	Meaning
`severity`	`str`	Usually `"error"` or `"warning"`.
`line`	`int	None`
`code`	`str`	Stable machine-readable issue code.
`message`	`str`	Human-readable message text.
`raw_line`	`str	None`

Helper:

issue.format() -> str

`ValidationReport`

Overall validation result for a feed.

Field	Type	Meaning
`source`	`str`	Original path or URL.
`records`	`int`	Number of data records processed.
`errors`	`int`	Number of validation errors.
`warnings`	`int`	Number of validation warnings.
`valid`	`bool`	`True` when `errors == 0`.
`issues`	`tuple[ValidationIssue, ...]`	Full issue list.

Helper:

report.as_dict() -> dict[str, object]

`QueryResult`

Lookup result returned by GeoFeed.query().

Field	Type	Meaning
`query`	`str`	Original query string.
`matches`	`tuple[GeofeedRecord, ...]`	Matching records, ordered most-specific first.

Helper:

result.as_dict() -> dict[str, object]

`DoctorLookup`

Lookup metadata returned inside DoctorResult.lookup.

Field	Type	Meaning
`lookup_strategy`	`str`	How the RDAP lookup was performed, such as `"ip-address"` or `"prefix-network-address"`.
`rdap_method`	`str`	RDAP lookup method used, such as `"rdap.org"` or `"iana-bootstrap"`.
`rdap_query`	`str`	The single IP address used for the RDAP lookup.
`bootstrap_url`	`str`	Initial RDAP object URL queried after method selection.
`bootstrap_source_url`	`str	None`
`resolved_urls`	`tuple[str, ...]`	RDAP object URLs visited during discovery, ordered from most specific to broader parents.
`referring_handle`	`str	None`
`referring_range`	`str	None`
`geofeed_url`	`str	None`
`geofeed_discovered_via`	`str	None`
`geofeed_reference_url`	`str	None`

Helper:

lookup.as_dict() -> dict[str, object]

`DoctorResult`

Lookup result returned by GeoFeed.doctor() or AsyncGeoFeed.doctor().

Field	Type	Meaning
`query`	`str`	Original query string.
`lookup`	`DoctorLookup`	RDAP discovery metadata and geofeed location information.
`matches`	`tuple[GeofeedRecord, ...]`	Matching geofeed rows, ordered most-specific first.

Helper:

result.as_dict() -> dict[str, object]

`GeoFeedInfo`

Summary statistics returned by GeoFeed.info().

Field	Type	Meaning
`source`	`str`	Original path or URL.
`total_records`	`int`	Number of parsed records.
`unique_prefixes`	`int`	Number of unique prefixes.
`ipv4_records`	`int`	Number of IPv4 records.
`ipv6_records`	`int`	Number of IPv6 records.
`unique_countries`	`int`	Count of distinct country values.
`unique_regions`	`int`	Count of distinct region values.
`unique_cities`	`int`	Count of distinct city values.
`unique_postal_codes`	`int`	Count of distinct postal-code values.
`duplicates`	`int`	Total records minus unique prefixes.
`errors`	`int`	Validation error count.
`warnings`	`int`	Validation warning count.
`metadata`	`dict[str, object]`	Reserved extensible metadata dictionary.

Helper:

info.as_dict() -> dict[str, object]

Error Handling

Common exceptions to expect when using the Python API:

ValueError: invalid output mode or an invalid query string passed to query(), doctor(), or lookup()
geofeed_tools.GeoFeedDiscoveryError: lookup() could not find any published geofeed URL for the query
FileNotFoundError or other OSError subclasses: local file read failures
geofeed_tools.loader.FetchError: remote HTTP(S) or RDAP fetch failures

Example:

from geofeed_tools import GeoFeed
from geofeed_tools.loader import FetchError

try:
	geofeed = GeoFeed("https://example.com/geofeed.csv")
	report = geofeed.validate(check_content_type=True)
except FetchError as exc:
	print(f"fetch failed: {exc}")

CLI Usage

Quick Start

The CLI entrypoint is:

geofeed-tools <command> [options]

Common quick-start examples:

# Validate and print a human-readable report
geofeed-tools validate geofeeds.csv

# Dump parsed records as JSON
geofeed-tools dump geofeeds.csv

# Dump parsed records as geofeed CSV
geofeed-tools dump geofeeds.csv --format csv

# Dump parsed records as a table
geofeed-tools dump geofeeds.csv --format table

# Normalize to canonical CSV and write to a file
geofeed-tools normalize geofeeds.csv --output normalized.csv

# Query by IP address or prefix
geofeed-tools query geofeeds.csv 192.0.2.200

# Discover a published geofeed for an address via RDAP
geofeed-tools doctor 31.133.128.1 --json

# Discover the published geofeed via RDAP and print matching rows only
geofeed-tools lookup 31.133.128.1

# Show summary statistics
geofeed-tools info geofeeds.csv

# Use hook mode in CI or pre-commit checks
geofeed-tools hook geofeeds.csv --strict

For command-specific help:

geofeed-tools --help
geofeed-tools validate --help

Common CLI Behavior

Most commands take a source positional argument pointing to a local file or HTTP(S) URL.
The doctor and lookup commands take only a QUERY positional argument because they discover the geofeed source dynamically via RDAP.
Every command supports cumulative -v or --verbose flags.
Verbosity levels are:
- -v: INFO
- -vv: DEBUG
- -vvv: TRACE
CLI support is optional. If the CLI extra is not installed, running the command exits with a message telling you to install .[cli].

Command Reference

`validate`

Usage:

geofeed-tools validate SOURCE [OPTIONS]

Validate a geofeed source and print either a text report or JSON.

Option	Default	Meaning
`--json`	off	Emit the validation report as JSON instead of text.
`--strict`	off	Exit with code `1` when warnings are present, not just errors.
`--check-aggregation`	off	Enable warnings for prefixes that could be safely aggregated.
`--no-sort-check`	off	Disable sort-order warnings.
`--no-content-type-check`	off	Disable `Content-Type` warnings for URL sources.
`-v`, `--verbose`	`0`	Increase log verbosity.

Examples:

geofeed-tools validate geofeeds.csv
geofeed-tools validate geofeeds.csv --json
geofeed-tools validate geofeeds.csv --check-aggregation
geofeed-tools validate geofeeds.csv --no-sort-check --no-content-type-check
geofeed-tools validate geofeeds.csv --strict

Exit behavior:

Exits 0 when there are no validation errors.
Exits 1 when validation errors are found.
With --strict, exits 1 when warnings are found too.

`dump`

Usage:

geofeed-tools dump SOURCE [OPTIONS]

Parse the geofeed and print records as a JSON array.

Option	Default	Meaning
`--format`, `-f`	`json`	Output format: `json`, `csv`, or `table`.
`--normalize`	off	Normalize records before dumping them.
`--no-validation`	off	Skip per-record validation annotations in JSON or table output.
`-v`, `--verbose`	`0`	Increase log verbosity.

Examples:

geofeed-tools dump geofeeds.csv
geofeed-tools dump geofeeds.csv --format csv
geofeed-tools dump geofeeds.csv --format table
geofeed-tools dump geofeeds.csv --no-validation
geofeed-tools dump geofeeds.csv --normalize

Output notes:

Default output is JSON.
--format csv emits standard 5-column geofeed rows.
--format table emits a GitHub-style table rendered with tabulate.
By default, JSON and table output include valid and validation_messages fields.
--no-validation affects JSON and table output only. CSV output always uses plain geofeed rows.
With --normalize, the output reflects normalized records rather than the original parsed rows.

`normalize`

Usage:

geofeed-tools normalize SOURCE [OPTIONS]

Normalize a geofeed and emit canonical CSV.

Option	Default	Meaning
`--output`, `-o`	stdout	Write normalized CSV to a file instead of stdout.
`--no-uppercase`	off	Do not uppercase country and region fields.
`--no-sort`	off	Do not sort output by IP family and network.
`--no-aggregate`	off	Do not collapse compatible prefixes into larger prefixes.
`--no-dedupe`	off	Do not remove exact duplicate rows when aggregation is disabled.
`--no-host-bit-fix`	off	Do not coerce prefixes with host bits set to their containing network.
`-v`, `--verbose`	`0`	Increase log verbosity.

Examples:

geofeed-tools normalize geofeeds.csv
geofeed-tools normalize geofeeds.csv --output normalized.csv
geofeed-tools normalize geofeeds.csv --no-uppercase --no-sort --no-aggregate --no-dedupe --no-host-bit-fix

Output notes:

Output is always CSV.
Without --output, the normalized CSV is printed to stdout.
With --output, the destination file is written using UTF-8 encoding.

`query`

Usage:

geofeed-tools query SOURCE QUERY [OPTIONS]

Query a geofeed using an IP address or CIDR prefix.

Argument	Meaning
`SOURCE`	Local file path or HTTP(S) geofeed URL.
`QUERY`	IP address or CIDR prefix to look up.

Option	Default	Meaning
`--all`	off	Return all matches instead of only the most specific match.
`--longer`	off	Include more-specific prefixes contained by the query prefix.
`--json`	off	Emit a JSON result object instead of CSV rows.
`-v`, `--verbose`	`0`	Increase log verbosity.

Examples:

geofeed-tools query geofeeds.csv 192.0.2.200
geofeed-tools query geofeeds.csv 192.0.2.200 --json
geofeed-tools query geofeeds.csv 192.0.2.0/24 --all --longer --json

Output and exit notes:

Default output is CSV containing matching rows only.
With --json, output is a JSON object with query and matches.
In CSV mode, no match prints an error to stderr and exits with code 1.
In JSON mode, no match returns an empty matches array and exits successfully.

`doctor`

Usage:

geofeed-tools doctor QUERY [OPTIONS]

Discover a published geofeed via RDAP and query it using an IP address or CIDR prefix.

Argument	Meaning
`QUERY`	IP address or CIDR prefix to diagnose.

Option	Default	Meaning
`--all`	off	Return all matches instead of only the most specific match.
`--longer`	off	Include more-specific prefixes contained by the query prefix.
`--rdap-method`	`rdap.org`	RDAP lookup method: `rdap.org` (default) or `iana-bootstrap`.
`--json`	off	Emit a JSON result object instead of the default text report.
`-v`, `--verbose`	`0`	Increase log verbosity.

Examples:

geofeed-tools doctor 31.133.128.1
geofeed-tools doctor 31.133.128.1 --json
geofeed-tools doctor 192.0.2.0/24 --all --longer
geofeed-tools doctor 31.133.128.1 --rdap-method iana-bootstrap

Output and exit notes:

Default output is a text report with the RDAP lookup trace, referring object, geofeed URL, and matching rows.
With --json, output is a JSON object containing query, lookup, and matches.
--rdap-method rdap.org is the default because it is faster for one-off lookups. --rdap-method iana-bootstrap avoids relying on rdap.org and queries the selected RIR service directly after reading the IANA bootstrap file.
Exits 0 when a geofeed is discovered and at least one matching row is found.
Exits 1 when no geofeed reference is published or when the discovered geofeed contains no matching row for the query.

`lookup`

Usage:

geofeed-tools lookup QUERY [OPTIONS]

Discover a published geofeed via RDAP and emit query-style output for an IP address or CIDR prefix.

Argument	Meaning
`QUERY`	IP address or CIDR prefix to look up.

Option	Default	Meaning
`--all`	off	Return all matches instead of only the most specific match.
`--longer`	off	Include more-specific prefixes contained by the query prefix.
`--rdap-method`	`rdap.org`	RDAP lookup method: `rdap.org` (default) or `iana-bootstrap`.
`--json`	off	Emit a JSON result object instead of CSV rows.
`-v`, `--verbose`	`0`	Increase log verbosity.

Examples:

geofeed-tools lookup 31.133.128.1
geofeed-tools lookup 31.133.128.1 --json
geofeed-tools lookup 192.0.2.0/24 --all --longer
geofeed-tools lookup 31.133.128.1 --rdap-method iana-bootstrap

Output and exit notes:

Default output is CSV containing matching rows only.
With --json, output is a JSON object with query and matches.
--rdap-method rdap.org is the default because it is faster for one-off lookups. --rdap-method iana-bootstrap avoids relying on rdap.org and queries the selected RIR service directly after reading the IANA bootstrap file.
Exits 0 when a geofeed is discovered and at least one matching row is found.
Exits 1 when no geofeed reference is published.
Exits 1 when the discovered geofeed contains no matching row for the query, including in JSON mode.

`info`

Usage:

geofeed-tools info SOURCE [OPTIONS]

Display high-level geofeed statistics.

Option	Default	Meaning
`--json`	off	Emit summary information as JSON instead of tables.
`-v`, `--verbose`	`0`	Increase log verbosity.

Examples:

geofeed-tools info geofeeds.csv
geofeed-tools info geofeeds.csv --json

Output notes:

Default output is a human-readable summary rendered as multiple GitHub-style tables.
JSON mode returns the same data as the Python GeoFeed.info(output="json") API.

`hook`

Usage:

geofeed-tools hook SOURCE [OPTIONS]

Run validation in a hook-friendly mode for CI, pre-commit, or automated checks.

Option	Default	Meaning
`--strict`	off	Fail when warnings are present, not just errors.
`--show-issues` / `--no-issues`	`--show-issues`	Print or suppress individual validation issue lines.
`-v`, `--verbose`	`0`	Increase log verbosity.

Examples:

geofeed-tools hook geofeeds.csv
geofeed-tools hook geofeeds.csv --no-issues
geofeed-tools hook geofeeds.csv --strict

Output and exit notes:

Issue lines and summary messages are written to stderr.
By default, the command fails only on errors.
With --strict, the command also fails on warnings.
Success summary format is hook: OK ...; failure summary format is hook: FAIL ....

GitHub Actions Integration

The hook command is designed to work well as a CI quality gate. This repository publishes a reusable workflow at .github/workflows/geofeed-validation.yml and also includes a caller example at examples/github-actions/geofeed-validation.yml.

How To Use It In Another Repository

Create a small workflow in your repository that calls the shared workflow with uses:

name: Validate geofeed

on:
  pull_request:
    paths:
      - "path/to/geofeed.csv"
  push:
    branches:
      - main
    paths:
      - "path/to/geofeed.csv"
  workflow_dispatch:

permissions:
  contents: read

jobs:
  geofeed-validation:
    uses: python-modules/geofeed-tools/.github/workflows/geofeed-validation.yml@main
    with:
      geofeed_path: path/to/geofeed.csv
      strict: false

Replace path/to/geofeed.csv with the tracked geofeed file path in your repository.

The above example disables strict mode validation - warnings are logged but permitted. To require strict mode validation set strict to true.

Testing

Recommended workflow commands:

make test
make test-html
make test-integration

make test-html writes a self-contained report to:

reports/pytest-report.html

Run non-integration tests:

pytest -m "not integration"

Run integration tests (real HTTP requests):

pytest -m integration

HTML test reports

pytest-html is configured in pyproject.toml. Running pytest generates a self-contained HTML report at:

reports/pytest-report.html

Open it in a browser after test execution.

Test Notes

Integration tests depend HTTP access to a set of well known geofeed files. The content of those files may change at any time resulting in different test failures.

Configuration

All tuneable defaults and external service endpoints are centralised in src/geofeed_tools/config.py. Edit that file to adjust any of the following without hunting through individual implementation modules:

Constant	Default	Purpose
`USER_AGENT`	`geofeed-tools/<version>`	`User-Agent` header sent with all outgoing HTTP requests.
`FETCH_TIMEOUT`	`30`	Seconds to wait for a remote HTTP response before giving up.
`URL_SCHEMES`	`("http://", "https://")`	Accepted URL schemes for remote geofeed sources.
`LOGGER_NAME`	`"geofeed_tools"`	Root logger name used throughout the package.
`TRACE_LEVEL`	`5`	Numeric log level below `DEBUG` used for verbose HTTP tracing (`-vvv`).
`LRU_COUNTRY_CACHE_SIZE`	`512`	Maximum entries in the ISO 3166-1 country code lookup cache.
`LRU_SUBDIVISION_CACHE_SIZE`	`4096`	Maximum entries in the ISO 3166-2 subdivision code lookup cache.
`DEFAULT_RDAP_METHOD`	`"rdap.org"`	RDAP lookup method used when no explicit method is specified.
`RDAP_ORG_ROOT_URL`	`https://rdap.org/`	Base URL for the rdap.org proxy service.
`RDAP_ORG_QUERY_TEMPLATE`	`https://rdap.org/ip/{}`	URL template for rdap.org IP queries.
`IANA_BOOTSTRAP_URLS`	IPv4/IPv6 IANA JSON endpoints	IANA RDAP bootstrap index URLs keyed by IP version.
`MAX_RDAP_DEPTH`	`8`	Maximum RDAP redirect hops before aborting a lookup.
`RDAP_ACCEPT`	`application/rdap+json, …`	`Accept` header sent with RDAP queries.
`JSON_ACCEPT`	`application/json, …`	`Accept` header sent with plain JSON requests (e.g. IANA bootstrap).

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github/workflows		.github/workflows
examples/github-actions		examples/github-actions
src/geofeed_tools		src/geofeed_tools
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

geofeed-tools

Basic Overview

Installation

Docker

Python API

Quick Start

Public Imports

AsyncGeoFeed

GeoFeed

Constructor

reload()

parse()

validate()

normalize()

query()

doctor()

lookup()

info()

Public Data Models

GeofeedRecord

ValidationIssue

ValidationReport

QueryResult

DoctorLookup

DoctorResult

GeoFeedInfo

Error Handling

CLI Usage

Quick Start

Common CLI Behavior

Command Reference

validate

dump

normalize

query

doctor

lookup

info

hook

GitHub Actions Integration

How To Use It In Another Repository

Testing

HTML test reports

Test Notes

Configuration

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`AsyncGeoFeed`

`GeoFeed`

`reload()`

`parse()`

`validate()`

`normalize()`

`query()`

`doctor()`

`lookup()`

`info()`

`GeofeedRecord`

`ValidationIssue`

`ValidationReport`

`QueryResult`

`DoctorLookup`

`DoctorResult`

`GeoFeedInfo`

`validate`

`dump`

`normalize`

`query`

`doctor`

`lookup`

`info`

`hook`

Packages