numclassify

What's new in v0.8.5

• why_hidden(property, n) -- explanation with verdict stripped, for practice/quiz mode
• practice_set(property, count, seed) -- balanced random YES/NO question generator
• PRACTICE_TYPES -- allowlist of 22 ICSE Class 10 syllabus types
• CLI numclassify quiz -- interactive practice mode
• Playground Practice tab -- guess-then-reveal quiz flow

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 2140+ categories, with zero external dependencies.

Why I built this

I was doing number programs in school (Armstrong numbers, perfect numbers, that kind of thing) and went looking for a Python package I could just import instead of rewriting the same checks every time. I couldn't find one. Every library I found computed things, factors, GCDs, primes, but none of them actually classified a number into the type it was.

Then I realized why: schools include these programs in the syllabus to teach students Python and basic mathematical logic, not so students can look up which number is which. The exercise is the point. So a library that just answers "is this Armstrong" defeats the purpose schools have for assigning it in the first place.

That's why why() and the explain functions exist. Instead of just returning True or False, numclassify shows the actual math, the same steps you'd write out by hand. The goal isn't to do the homework for you. It's to be the thing you check your own work against, or use to explore beyond what one assignment asks for.

153   →  Armstrong, Harshad, Triangular, Abundant, ...
1729  →  Taxicab (Hardy-Ramanujan), Carmichael, Harshad, ...
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

The standout feature is why() -- it explains the reasoning, not just the result:

import numclassify as nc

# Not just True or False — shows you the actual math
nc.why("armstrong", 153)
# "153 is Armstrong because: 153 = 1^3 + 5^3 + 3^3 = 1 + 125 + 27 = 153"

nc.why("perfect", 28)
# "28 is Perfect because: proper divisors = {1, 2, 4, 7, 14}, sum = 28"

Basic usage

import numclassify as nc

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

# Classify a single number
nc.classify(1729)
# {
#   'number': 1729,
#   'score': 22,            # total true properties (incl. figurate)
#   'notable_score': 18,    # score excluding polygonal figurate noise
#   'true_properties': ['Taxicab', 'Carmichael', ...],
#   'categories': {'primes': [...], 'sequences': [...], ...}
# }

# 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, min_score=20):
    print(result)

# Stream only numbers with a specific property
for result in nc.stream(1, 10_000, has_property="prime"):
    print(result)

# All true properties of a number (returns a dict of True properties)
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

# Explain why a number has a property
numclassify why armstrong 153

# Practice mode: guess before you see the answer
numclassify quiz armstrong --count 10
numclassify quiz --list-types

# Multi-property query with AND/OR/NOT logic
numclassify query 1 1000 --has prime palindrome

Number Categories

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.

Practice mode

Learn number classification by guessing, not by calling a function.

numclassify quiz armstrong --count 10
numclassify quiz --list-types

Guess YES or NO for each number, then see the actual math (divisors, digit sums, factorizations) before the verdict. Built for ICSE Class 10 Computer Applications topics: Armstrong, Perfect, Prime, Harshad, Circular Prime, Emirp, Fibonacci, Buzz, Spy, Automorphic, Neon, Duck, Disarium, Kaprekar, Happy, Sunny, Strong, Twin Prime, Abundant, Deficient.

Also in the playground under the Practice tab.

API Reference

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

More

• Contributing -- how to add new number types
• Security -- reporting vulnerabilities
• Performance -- benchmarks and complexity notes
• Architecture -- registry internals and module map
• Changelog -- full version history

License

MIT © 2026 Aratrik Ghosh