Skip to content

Commit a18eb68

Browse files
erichutchinsclaude
andcommitted
docs: add IP extension types example to README, fix spur column header
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 58bbf02 commit a18eb68

1 file changed

Lines changed: 32 additions & 1 deletion

File tree

README.md

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,37 @@ shape: (6, 2)
3434
└─────────────────┴────────────┘
3535
```
3636

37+
### IP extension types
38+
39+
IPTools provides two Arrow extension types for storing IP addresses efficiently.
40+
`IPv4` uses 4-byte `UInt32` storage; `IPAddress` uses 16-byte binary and handles
41+
both IPv4 and IPv6. Both types survive Parquet and IPC round-trips with dtype preserved.
42+
43+
```python
44+
>>> import polars as pl
45+
>>> import polars_iptools as ip
46+
47+
>>> df = pl.DataFrame({"ip": ["8.8.8.8", "2606:4700::1111", "192.168.1.1", "invalid"]})
48+
>>> df.with_columns(ip.to_address("ip"))
49+
shape: (4, 2)
50+
┌─────────────────┬─────────────────┐
51+
│ ip ┆ ip │
52+
------
53+
str ┆ ip_addr │
54+
╞═════════════════╪═════════════════╡
55+
8.8.8.8 ┆ 8.8.8.8 │
56+
2606:4700::11112606:4700::1111
57+
192.168.1.1 ┆ 192.168.1.1 │
58+
│ invalid ┆ null │
59+
└─────────────────┴─────────────────┘
60+
61+
>>> # Write typed column to Parquet — dtype is preserved on read
62+
>>> typed = df.with_columns(ip.to_address("ip"))
63+
>>> typed.write_parquet("/tmp/ips.parquet")
64+
>>> pl.read_parquet("/tmp/ips.parquet").dtypes
65+
[String, IPAddress]
66+
```
67+
3768
### `is_in` but for network ranges
3869

3970
Pandas and Polars have `is_in` functions to perform membership lookups. IPTools extends this to enable IP address membership in IP _networks_. This function works seamlessly with both IPv4 and IPv6 addresses and converts the specified networks into a [Level-Compressed trie (LC-Trie)](https://github.com/Orange-OpenSource/iptrie) for fast, efficient lookups.
@@ -110,7 +141,7 @@ shape: (4, 2)
110141

111142
shape: (3, 2)
112143
┌─────────────────┬─────────────────────────────────┐
113-
│ ip ┆ geoip
144+
│ ip ┆ spur
114145
------
115146
str ┆ struct[7] │
116147
╞═════════════════╪═════════════════════════════════╡

0 commit comments

Comments
 (0)