numclassify 0.1.1__tar.gz → 0.2.0__tar.gz

{numclassify-0.1.1 → numclassify-0.2.0}/.gitignore

@@ -1,3 +1,4 @@
+.pytest_cache/
 __pycache__/
 *.pyc
 *.pyo

{numclassify-0.1.1 → numclassify-0.2.0}/CHANGELOG.md

@@ -6,6 +6,19 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
+## [0.2.0] - 2026-05-11
+
+### Added
+- `classify(n)` — returns `{"number": n, "true_properties": [...], "score": int}`
+- `classify_batch(numbers)` — classify a list of numbers in one call
+- `random_number(max_n=10000)` — classify a random number
+- `find_by_property(start, end, **filters)` — query numbers by property name/value
+- `stream(start, end)` — memory-safe generator yielding classify results
+- `numclassify compare <a> <b> [--json]` — new CLI command showing shared/exclusive properties
+- Windows ANSI color fix via `SetConsoleMode` VT100 flag
+- `py.typed` marker added (PEP 561 compliant)
+- Full type hints on all public API functions
+
 ## [0.1.1] - 2026-05-06
 ### Fixed
 - cli.py: Fixed imports to use numclassify._core instead of numclassify

{numclassify-0.1.1 → numclassify-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numclassify
-Version: 0.1.1
+Version: 0.2.0
 Summary: The most comprehensive Python library for number classification — 3000+ number types
 Project-URL: Homepage, https://github.com/aratrikghosh2011-tech/numclassify
 Project-URL: Repository, https://github.com/aratrikghosh2011-tech/numclassify
@@ -26,26 +26,27 @@ Description-Content-Type: text/markdown
 
 # numclassify
 
-> The most comprehensive Python library for number classification — 3000+ number types, zero dependencies.
+The most comprehensive Python library for number classification — 3000+ number types, zero dependencies.
 
 [![PyPI version](https://img.shields.io/pypi/v/numclassify)](https://pypi.org/project/numclassify/)
+[![Downloads](https://img.shields.io/pypi/dm/numclassify)](https://pypi.org/project/numclassify/)
 [![Python versions](https://img.shields.io/pypi/pyversions/numclassify)](https://pypi.org/project/numclassify/)
 [![License MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/aratrikghosh2011-tech/numclassify/blob/main/LICENSE)
 [![Tests](https://img.shields.io/github/actions/workflow/status/aratrikghosh2011-tech/numclassify/ci.yml?label=tests)](https://github.com/aratrikghosh2011-tech/numclassify/actions/workflows/ci.yml)
 
 ---
 
-## Why numclassify?
+## Overview
 
-Most number-theory libraries — `labmath`, `eulerlib`, `pyntlib` — answer *computational* questions: factor this, find the GCD, generate primes up to N.
+Most number-theory libraries — `labmath`, `eulerlib`, `pyntlib` — are built around computation: factoring integers, finding GCDs, generating primes. `numclassify` solves a different problem: **given a number, what is it?**
 
-`numclassify` answers a different question: **what kind of number is this?**
-
-- `153` → Armstrong, Narcissistic, Harshad, Triangular, Abundant…
-- `1729` → Taxicab (Hardy-Ramanujan), Zeisel, Carmichael…
-- `28` → Perfect, Triangular, Hexagonal, Semiprime…
+```
+153   →  Armstrong, Harshad, Triangular, Abundant ...
+1729  →  Taxicab (Hardy-Ramanujan), Carmichael, Zeisel ...
+28    →  Perfect, Triangular, Hexagonal, Semiprime ...
+```
 
-Over **3000 named number types**, instant lookup, no external dependencies.
+Over **3000 named number types** are supported, with instant lookup, no external dependencies, and a fully typed API.
 
 ---
 
@@ -55,7 +56,7 @@ Over **3000 named number types**, instant lookup, no external dependencies.
 pip install numclassify
 ```
 
-Or clone and install in editable mode:
+To install from source in editable mode:
 
 ```bash
 git clone https://github.com/aratrikghosh2011-tech/numclassify.git
@@ -71,20 +72,32 @@ pip install -e .
 import numclassify as nc
 
 # Boolean checks
-nc.is_prime(17)          # True
-nc.is_armstrong(153)     # True
-nc.is_perfect(28)        # True
+nc.is_prime(17)            # True
+nc.is_perfect(28)          # True
+
+# Classify a single number
+nc.classify(1729)
+# {'number': 1729, 'true_properties': ['Taxicab', 'Carmichael', ...], 'score': 22}
+
+# Classify multiple numbers at once
+nc.classify_batch([6, 28, 496])
+
+# Query by property
+nc.find_by_property(start=1, end=1000, Perfect=True)
+# [6, 28, 496]
+
+# Memory-safe streaming over large ranges
+for result in nc.stream(1, 1_000_000):
+    if result['score'] > 30:
+        print(result)
+
+# Random number classification
+nc.random_number()
 
 # All true properties of a number
 nc.get_true_properties(1729)
-# ['taxicab', 'zeisel', 'carmichael', 'odd', 'composite',
-#  'deficient', 'squarefree', 'cubefree', 'powerful_not_perfect_power']
-
-# Search a range
-nc.find_in_range(nc.is_armstrong, 1, 10000)
-# [1, 2, 3, 4, 5, 6, 7, 8, 9, 153, 370, 371, 407, 1634, 8208, 9474]
 
-# Pretty-print everything about a number
+# Pretty-print everything
 nc.print_properties(153)
 # ┌─────────────────────────────────────────┐
 # │  Properties of 153                      │
@@ -132,6 +145,16 @@ $ numclassify range 1 20 --filter prime
 2, 3, 5, 7, 11, 13, 17, 19
 ```
 
+**Compare two numbers:**
+```bash
+$ numclassify compare 6 28
+Comparing 6 and 28
+──────────────────
+Shared (13): Perfect, Triangular, Hexagonal, ...
+Only in 6 (21): Armstrong, Factorial, Palindrome, ...
+Only in 28 (8): Happy, Keith, Padovan, ...
+```
+
 **List all registered types in a category:**
 ```bash
 $ numclassify list --category primes
@@ -156,23 +179,23 @@ Examples:    1, 2, 3, 153, 370, 371, 407, 1634, 8208, 9474
 
 | 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, Catalan… |
-| Recreational | 5 | Kaprekar, Automorphic, Palindrome… |
+| 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, Catalan |
+| Recreational | 5 | Kaprekar, Automorphic, Palindrome |
 | **Total** | **3000+** | |
 
 ---
 
-## Adding Your Own Number Type
+## Adding Custom Number Types
 
-The `@register` decorator lets you plug in custom types in 6 lines:
+The `@register` decorator lets you define and integrate your own number types in a few lines. Once registered, the type is automatically available through the full API and CLI.
 
 ```python
 from numclassify import register
@@ -181,7 +204,6 @@ from numclassify import register
 def is_my_type(n: int) -> bool:
     return n > 0 and n % 7 == 0 and str(n)[0] == "4"
 
-# Now works everywhere
 import numclassify as nc
 nc.is_my_type(49)              # False  (doesn't start with 4)
 nc.is_my_type(42)              # True
@@ -194,24 +216,28 @@ nc.get_true_properties(42)     # [..., 'my_type', ...]
 
 | Function | Description |
 |---|---|
-| `is_prime(n)` | Returns `True` if `n` is a standard prime |
-| `is_armstrong(n)` | Returns `True` if `n` is a narcissistic/Armstrong number |
-| `get_all_properties(n)` | Dict of every registered type → `True`/`False` |
-| `get_true_properties(n)` | List of only the properties that are `True` |
+| `classify(n)` | Returns a dict with the number, its true properties, and a score |
+| `classify_batch(numbers)` | Classify a list of numbers; returns a list of dicts |
+| `random_number(max_n)` | Classify a randomly selected number up to `max_n` |
+| `find_by_property(start, end, **filters)` | Find numbers in a range matching given property filters |
+| `stream(start, end)` | Generator yielding classify results one at a time; memory-safe |
+| `is_prime(n)` | Returns `True` if `n` is prime |
+| `is_armstrong(n)` | Returns `True` if `n` is an Armstrong (narcissistic) number |
+| `get_all_properties(n)` | Dict mapping every registered type to `True` or `False` |
+| `get_true_properties(n)` | List of only the properties that hold for `n` |
 | `print_properties(n)` | Pretty-prints a formatted property table to stdout |
 | `find_in_range(fn, lo, hi)` | All integers in `[lo, hi]` where `fn` returns `True` |
-| `find_all_in_range(lo, hi)` | Dict mapping every number in range to its true properties |
-| `count_properties(n)` | Count of how many types apply to `n` |
-| `most_special_in_range(lo, hi)` | The number in `[lo, hi]` with the most true properties |
+| `count_properties(n)` | Number of types that apply to `n` |
+| `most_special_in_range(lo, hi)` | Number in `[lo, hi]` with the greatest count of true properties |
 
-Full API docs: [github.com/aratrikghosh2011-tech/numclassify](https://github.com/aratrikghosh2011-tech/numclassify)
+Full API documentation: [github.com/aratrikghosh2011-tech/numclassify](https://github.com/aratrikghosh2011-tech/numclassify)
 
 ---
 
 ## Requirements
 
 - Python 3.8 or higher
-- Zero external dependencies
+- No external dependencies
 
 ---
 

{numclassify-0.1.1 → numclassify-0.2.0}/README.md

@@ -1,25 +1,26 @@
 # numclassify
 
-> The most comprehensive Python library for number classification — 3000+ number types, zero dependencies.
+The most comprehensive Python library for number classification — 3000+ number types, zero dependencies.
 
 [![PyPI version](https://img.shields.io/pypi/v/numclassify)](https://pypi.org/project/numclassify/)
+[![Downloads](https://img.shields.io/pypi/dm/numclassify)](https://pypi.org/project/numclassify/)
 [![Python versions](https://img.shields.io/pypi/pyversions/numclassify)](https://pypi.org/project/numclassify/)
 [![License MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/aratrikghosh2011-tech/numclassify/blob/main/LICENSE)
 [![Tests](https://img.shields.io/github/actions/workflow/status/aratrikghosh2011-tech/numclassify/ci.yml?label=tests)](https://github.com/aratrikghosh2011-tech/numclassify/actions/workflows/ci.yml)
 
 ---
 
-## Why numclassify?
+## Overview
 
-Most number-theory libraries — `labmath`, `eulerlib`, `pyntlib` — answer *computational* questions: factor this, find the GCD, generate primes up to N.
+Most number-theory libraries — `labmath`, `eulerlib`, `pyntlib` — are built around computation: factoring integers, finding GCDs, generating primes. `numclassify` solves a different problem: **given a number, what is it?**
 
-`numclassify` answers a different question: **what kind of number is this?**
-
-- `153` → Armstrong, Narcissistic, Harshad, Triangular, Abundant…
-- `1729` → Taxicab (Hardy-Ramanujan), Zeisel, Carmichael…
-- `28` → Perfect, Triangular, Hexagonal, Semiprime…
+```
+153   →  Armstrong, Harshad, Triangular, Abundant ...
+1729  →  Taxicab (Hardy-Ramanujan), Carmichael, Zeisel ...
+28    →  Perfect, Triangular, Hexagonal, Semiprime ...
+```
 
-Over **3000 named number types**, instant lookup, no external dependencies.
+Over **3000 named number types** are supported, with instant lookup, no external dependencies, and a fully typed API.
 
 ---
 
@@ -29,7 +30,7 @@ Over **3000 named number types**, instant lookup, no external dependencies.
 pip install numclassify
 ```
 
-Or clone and install in editable mode:
+To install from source in editable mode:
 
 ```bash
 git clone https://github.com/aratrikghosh2011-tech/numclassify.git
@@ -45,20 +46,32 @@ pip install -e .
 import numclassify as nc
 
 # Boolean checks
-nc.is_prime(17)          # True
-nc.is_armstrong(153)     # True
-nc.is_perfect(28)        # True
+nc.is_prime(17)            # True
+nc.is_perfect(28)          # True
+
+# Classify a single number
+nc.classify(1729)
+# {'number': 1729, 'true_properties': ['Taxicab', 'Carmichael', ...], 'score': 22}
+
+# Classify multiple numbers at once
+nc.classify_batch([6, 28, 496])
+
+# Query by property
+nc.find_by_property(start=1, end=1000, Perfect=True)
+# [6, 28, 496]
+
+# Memory-safe streaming over large ranges
+for result in nc.stream(1, 1_000_000):
+    if result['score'] > 30:
+        print(result)
+
+# Random number classification
+nc.random_number()
 
 # All true properties of a number
 nc.get_true_properties(1729)
-# ['taxicab', 'zeisel', 'carmichael', 'odd', 'composite',
-#  'deficient', 'squarefree', 'cubefree', 'powerful_not_perfect_power']
-
-# Search a range
-nc.find_in_range(nc.is_armstrong, 1, 10000)
-# [1, 2, 3, 4, 5, 6, 7, 8, 9, 153, 370, 371, 407, 1634, 8208, 9474]
 
-# Pretty-print everything about a number
+# Pretty-print everything
 nc.print_properties(153)
 # ┌─────────────────────────────────────────┐
 # │  Properties of 153                      │
@@ -106,6 +119,16 @@ $ numclassify range 1 20 --filter prime
 2, 3, 5, 7, 11, 13, 17, 19
 ```
 
+**Compare two numbers:**
+```bash
+$ numclassify compare 6 28
+Comparing 6 and 28
+──────────────────
+Shared (13): Perfect, Triangular, Hexagonal, ...
+Only in 6 (21): Armstrong, Factorial, Palindrome, ...
+Only in 28 (8): Happy, Keith, Padovan, ...
+```
+
 **List all registered types in a category:**
 ```bash
 $ numclassify list --category primes
@@ -130,23 +153,23 @@ Examples:    1, 2, 3, 153, 370, 371, 407, 1634, 8208, 9474
 
 | 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, Catalan… |
-| Recreational | 5 | Kaprekar, Automorphic, Palindrome… |
+| 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, Catalan |
+| Recreational | 5 | Kaprekar, Automorphic, Palindrome |
 | **Total** | **3000+** | |
 
 ---
 
-## Adding Your Own Number Type
+## Adding Custom Number Types
 
-The `@register` decorator lets you plug in custom types in 6 lines:
+The `@register` decorator lets you define and integrate your own number types in a few lines. Once registered, the type is automatically available through the full API and CLI.
 
 ```python
 from numclassify import register
@@ -155,7 +178,6 @@ from numclassify import register
 def is_my_type(n: int) -> bool:
     return n > 0 and n % 7 == 0 and str(n)[0] == "4"
 
-# Now works everywhere
 import numclassify as nc
 nc.is_my_type(49)              # False  (doesn't start with 4)
 nc.is_my_type(42)              # True
@@ -168,24 +190,28 @@ nc.get_true_properties(42)     # [..., 'my_type', ...]
 
 | Function | Description |
 |---|---|
-| `is_prime(n)` | Returns `True` if `n` is a standard prime |
-| `is_armstrong(n)` | Returns `True` if `n` is a narcissistic/Armstrong number |
-| `get_all_properties(n)` | Dict of every registered type → `True`/`False` |
-| `get_true_properties(n)` | List of only the properties that are `True` |
+| `classify(n)` | Returns a dict with the number, its true properties, and a score |
+| `classify_batch(numbers)` | Classify a list of numbers; returns a list of dicts |
+| `random_number(max_n)` | Classify a randomly selected number up to `max_n` |
+| `find_by_property(start, end, **filters)` | Find numbers in a range matching given property filters |
+| `stream(start, end)` | Generator yielding classify results one at a time; memory-safe |
+| `is_prime(n)` | Returns `True` if `n` is prime |
+| `is_armstrong(n)` | Returns `True` if `n` is an Armstrong (narcissistic) number |
+| `get_all_properties(n)` | Dict mapping every registered type to `True` or `False` |
+| `get_true_properties(n)` | List of only the properties that hold for `n` |
 | `print_properties(n)` | Pretty-prints a formatted property table to stdout |
 | `find_in_range(fn, lo, hi)` | All integers in `[lo, hi]` where `fn` returns `True` |
-| `find_all_in_range(lo, hi)` | Dict mapping every number in range to its true properties |
-| `count_properties(n)` | Count of how many types apply to `n` |
-| `most_special_in_range(lo, hi)` | The number in `[lo, hi]` with the most true properties |
+| `count_properties(n)` | Number of types that apply to `n` |
+| `most_special_in_range(lo, hi)` | Number in `[lo, hi]` with the greatest count of true properties |
 
-Full API docs: [github.com/aratrikghosh2011-tech/numclassify](https://github.com/aratrikghosh2011-tech/numclassify)
+Full API documentation: [github.com/aratrikghosh2011-tech/numclassify](https://github.com/aratrikghosh2011-tech/numclassify)
 
 ---
 
 ## Requirements
 
 - Python 3.8 or higher
-- Zero external dependencies
+- No external dependencies
 
 ---
 

numclassify-0.2.0/docs/api.md

@@ -0,0 +1,25 @@
+# API Reference
+
+## classify(n)
+Returns dict with number, true_properties list, and score.
+
+## classify_batch(numbers)
+Classify a list of integers.
+
+## random_number(max_n=10000)
+Classify a random integer up to max_n.
+
+## find_by_property(start, end, **filters)
+Find numbers matching property filters.
+
+## stream(start, end)
+Memory-safe generator over large ranges.
+
+## Utilities
+- get_all_properties(n)
+- get_true_properties(n)
+- print_properties(n)
+- count_properties(n)
+- most_special_in_range(lo, hi)
+- find_in_range(fn, lo, hi)
+- is_prime(n), is_armstrong(n), is_perfect(n)

numclassify-0.2.0/docs/changelog.md

@@ -0,0 +1,3 @@
+# Changelog
+
+See the full changelog on GitHub.

numclassify-0.2.0/docs/cli.md

@@ -0,0 +1,22 @@
+# CLI Reference
+
+## check
+    numclassify check 1729
+    numclassify check 1729 --json
+
+## compare
+    numclassify compare 6 28
+    numclassify compare 6 28 --json
+
+## find
+    numclassify find armstrong --limit 10
+
+## range
+    numclassify range 1 100 --filter prime
+
+## info
+    numclassify info armstrong
+
+## list
+    numclassify list
+    numclassify list --category primes

numclassify-0.2.0/docs/index.md

@@ -0,0 +1,23 @@
+# numclassify
+
+The most comprehensive Python number classification library - 3000+ types, zero dependencies.
+
+## Installation
+
+    pip install numclassify
+
+## Quick Start
+
+    import numclassify as nc
+    nc.classify(1729)
+    nc.classify_batch([6, 28, 496])
+    nc.find_by_property(start=1, end=1000, Perfect=True)
+    nc.random_number()
+
+## Why numclassify?
+
+- 153: Armstrong, Narcissistic, Harshad, Triangular...
+- 1729: Taxicab, Carmichael, Dodecagonal...
+- 28: Perfect, Triangular, Hexagonal, Keith...
+
+3000+ named number types. Instant lookup. Zero dependencies.

numclassify-0.2.0/mkdocs.yml

@@ -0,0 +1,26 @@
+site_name: numclassify
+site_description: The most comprehensive Python number classification library - 3000+ types
+site_url: https://aratrikghosh2011-tech.github.io/numclassify/
+repo_url: https://github.com/aratrikghosh2011-tech/numclassify
+repo_name: aratrikghosh2011-tech/numclassify
+
+theme:
+  name: material
+  palette:
+    primary: indigo
+    accent: indigo
+  features:
+    - navigation.tabs
+    - navigation.top
+    - content.code.copy
+
+nav:
+  - Home: index.md
+  - API Reference: api.md
+  - CLI: cli.md
+  - Changelog: changelog.md
+
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - tables