numclassify 0.3.1

The most comprehensive Python library for number classification - 3000+ number types

numclassify

Given a number, what is it?

Most number-theory libraries — labmath, eulerlib, pyntlib — compute things: factor integers, find GCDs, generate primes. numclassify solves a different problem. Hand it a number and it tells you every named mathematical type that number belongs to, across 3000+ categories, with zero external dependencies.

153   →  Armstrong, Harshad, Triangular, Abundant, ...
1729  →  Taxicab (Hardy-Ramanujan), Carmichael, Zeisel, ...
28    →  Perfect, Triangular, Hexagonal, Semiprime, ...

Try it in your browser: numclassify Playground

---

Installation

pip install numclassify

Python 3.8+ required. No external dependencies.

---

Quick Start

import numclassify as nc

# Boolean checks
nc.is_prime(17)       # True
nc.is_perfect(28)     # True

# Classify a single number — returns number, true properties, and a score
nc.classify(1729)
# {'number': 1729, 'true_properties': ['Taxicab', 'Carmichael', ...], 'score': 22}

# Batch classify
nc.classify_batch([6, 28, 496])

# Find numbers in a range with a given property
nc.find_by_property(start=1, end=1000, Perfect=True)
# [6, 28, 496]

# Stream over large ranges without loading everything into memory
for result in nc.stream(1, 1_000_000):
    if result['score'] > 30:
        print(result)

# All true properties of a number
nc.get_true_properties(1729)

# Pretty-print a formatted table
nc.print_properties(153)
# ┌─────────────────────────────────────────┐
# │  Properties of 153                      │
# ├─────────────────────────────────────────┤
# │  armstrong         ✓                    │
# │  harshad           ✓                    │
# │  triangular        ✓                    │
# │  ...                                    │
# └─────────────────────────────────────────┘

---

CLI

# Classify a number
numclassify check 1729

# JSON output for piping
numclassify check 153 --json

# Find numbers of a type
numclassify find armstrong --limit 10

# Filter a range
numclassify range 1 20 --filter prime

# Compare two numbers
numclassify compare 6 28

# List all types in a category
numclassify list --category primes

# Get info and OEIS reference for a type
numclassify info armstrong

---

Number Categories

Category	Count	Examples
Polygonal figurate	~998	Triangular, Square, Pentagonal, Chiliagonal
Centered polygonal	~998	Centered Triangular, Centered Hexagonal
Prime families	41	Twin, Mersenne, Sophie Germain, Wilson, Safe
Digital invariants	10	Armstrong, Spy, Harshad, Disarium, Happy, Neon
Divisor-based	27	Perfect, Abundant, Weird, Amicable, Practical
Sequences	15	Fibonacci, Lucas, Catalan, Bell, Padovan
Powers	13	Perfect Square, Taxicab, Sum of Two Squares
Number theory	14	Evil, Carmichael, Keith, Autobiographical
Combinatorial	10	Factorial, Primorial, Subfactorial
Recreational	5	Kaprekar, Automorphic, Palindrome
Total	3000+

---

Custom Types

The @register decorator lets you add your own number types. Once registered, the type appears everywhere — classify(), find_by_property(), the CLI, all of it.

from numclassify import register

@register(name="my_type", category="custom")
def is_my_type(n: int) -> bool:
    return n > 0 and n % 7 == 0 and str(n)[0] == "4"

import numclassify as nc
nc.is_my_type(42)           # True
nc.get_true_properties(42)  # [..., 'my_type', ...]

See examples/ for runnable scripts covering all major features.

---

API Reference

Function	Description
classify(n)	Returns {number, true_properties, score}
classify_batch(numbers)	Classify a list; returns list of dicts
random_number(max_n)	Classify a randomly selected number
find_by_property(start, end, **filters)	Numbers in range matching property filters
stream(start, end)	Generator — memory-safe range classification
get_all_properties(n)	Dict of every type mapped to True/False
get_true_properties(n)	List of True property names only
print_properties(n)	Pretty-print property table to stdout
count_properties(n)	Count of True properties
most_special_in_range(lo, hi)	Number in range with the most True properties
find_in_range(fn, lo, hi)	Numbers where fn returns True
find_all_in_range(lo, hi)	Dict mapping each number to its true properties
register	Decorator to add custom number types
is_prime(n)	Convenience boolean
is_armstrong(n)	Convenience boolean
is_perfect(n)	Convenience boolean

Full docs: aratrikghosh2011-tech.github.io/numclassify

---

License

MIT © 2026 Aratrik Ghosh