numclassify 0.1.1__tar.gz → 0.2.1__tar.gz

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

@@ -1,3 +1,4 @@
+.pytest_cache/
 __pycache__/
 *.pyc
 *.pyo
@@ -8,3 +9,4 @@ dist/
 *.egg-info/
 .env
 .venv 
+site/

{numclassify-0.1.1 → numclassify-0.2.1}/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.2.1/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to numclassify
+
+## Adding a New Number Type
+
+The fastest way to contribute is adding a new number type using the `@register` decorator.
+
+### Step 1 \u2014 Write your function
+
+```python
+from numclassify import register
+
+@register(name="My Type", category="recreational")
+def is_my_type(n: int) -> bool:
+    return n > 0 and n % 7 == 0
+```
+
+That's it. Your type is now available via:
+- `nc.get_all_properties(n)`
+- `nc.get_true_properties(n)`
+- `nc.find_in_range(nc.is_my_type, 1, 1000)`
+- `numclassify find my_type` in the CLI
+
+### Step 2 \u2014 Add it to the right module
+
+Place your function in the appropriate file under `numclassify/_core/`:
+
+| Module | Types |
+|---|---|
+| `primes.py` | Prime families |
+| `figurate.py` | Polygonal/figurate numbers |
+| `divisors.py` | Divisor-based (perfect, abundant...) |
+| `digital.py` | Digit-based (Armstrong, Harshad...) |
+| `sequences.py` | Number sequences (Fibonacci, Lucas...) |
+| `powers.py` | Powers and sums |
+| `number_theory.py` | Number theory properties |
+| `combinatorial.py` | Combinatorial numbers |
+| `recreational.py` | Recreational/fun types |
+
+### Step 3 \u2014 Add a test
+
+Add a test in `tests/` following the existing pattern:
+
+```python
+def test_is_my_type():
+    assert nc.is_my_type(7) == True
+    assert nc.is_my_type(1) == False
+```
+
+### Step 4 \u2014 Submit a PR
+
+```bash
+git checkout -b add-my-type
+git add .
+git commit -m "Add My Type number classification"
+git push origin add-my-type
+```
+
+Then open a pull request on GitHub.
+
+## Running Tests
+
+```bash
+cd numclassify
+python -m pytest tests/ -v
+```
+
+## Code Style
+
+- Pure Python, no external dependencies
+- Type hints required on all functions
+- Function name must start with `is_` for boolean classifiers

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

@@ -1,15 +1,16 @@
 Metadata-Version: 2.4
 Name: numclassify
-Version: 0.1.1
-Summary: The most comprehensive Python library for number classification — 3000+ number types
+Version: 0.2.1
+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
+Project-URL: Documentation, https://aratrikghosh2011-tech.github.io/numclassify/
 Project-URL: Issues, https://github.com/aratrikghosh2011-tech/numclassify/issues
 Author-email: Aratrik Ghosh <aratrikghosh2011@gmail.com>
 License: MIT
 License-File: LICENSE
 Keywords: armstrong,classification,figurate,mathematics,number-theory,prime
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -20,32 +21,34 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Requires-Python: >=3.8
 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 +58,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 +74,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 +147,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 +181,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 +206,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 +218,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.1}/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.1/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.1/docs/changelog.md

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

numclassify-0.2.1/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.1/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.1/examples/basic_usage.py

@@ -0,0 +1,6 @@
+import numclassify as nc
+
+print(nc.classify(1729))
+print(nc.classify_batch([6, 28, 496]))
+print(nc.get_true_properties(153))
+print(nc.count_properties(28))

numclassify-0.2.1/examples/custom_type.py

@@ -0,0 +1,12 @@
+from numclassify import register
+import numclassify as nc
+
+# Add a custom number type using the @register decorator
+@register(name="Lucky Seven Multiple", category="recreational")
+def is_lucky_seven_multiple(n: int) -> bool:
+    return n > 0 and n % 7 == 0 and "7" in str(n)
+
+# Now works across the entire API
+print(nc.is_lucky_seven_multiple(77))   # True
+print(nc.is_lucky_seven_multiple(14))   # False
+print("Lucky Seven Multiples under 200:", nc.find_in_range(nc.is_lucky_seven_multiple, 1, 200))

numclassify-0.2.1/examples/find_perfect_numbers.py

@@ -0,0 +1,9 @@
+import numclassify as nc
+
+# Find all perfect numbers under 10000
+perfect = nc.find_by_property(start=1, end=10000, Perfect=True)
+print("Perfect numbers:", perfect)
+
+# Find numbers that are both perfect and odious
+perfect_odious = nc.find_by_property(start=1, end=10000, Perfect=True, Odious=True)
+print("Perfect and Odious:", perfect_odious)

numclassify-0.2.1/examples/random_classify.py

@@ -0,0 +1,6 @@
+import numclassify as nc
+
+# Classify 5 random numbers
+for _ in range(5):
+    result = nc.random_number(max_n=100000)
+    print(f"{result['number']}: {result['score']} properties \u2014 {result['true_properties'][:3]}")

numclassify-0.2.1/examples/stream_large_range.py

@@ -0,0 +1,7 @@
+import numclassify as nc
+
+# Memory-safe streaming over large range
+# Print any number with score > 30
+for result in nc.stream(1, 10000):
+    if result["score"] > 30:
+        print(f"{result['number']}: score={result['score']}, types={result['true_properties'][:5]}")

numclassify-0.2.1/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

numclassify-0.2.1/numclassify/__init__.py

@@ -0,0 +1,181 @@
+"""
+numclassify
+~~~~~~~~~~~
+The most comprehensive Python library for number classification.
+Importing this package triggers registration of all built-in classification
+functions via their ``@register`` decorators.
+
+Public API
+----------
+.. autosummary::
+   is_prime
+   is_armstrong
+   is_perfect
+   get_all_properties
+   get_true_properties
+   print_properties
+   find_in_range
+   find_all_in_range
+   count_properties
+   most_special_in_range
+   classify
+   classify_batch
+   random_number
+   find_by_property
+   stream
+"""
+
+from __future__ import annotations
+del annotations
+
+__version__ = "0.2.1"
+
+# --- Import all _core submodules so @register decorators fire at import time ---
+from numclassify._core import primes as _primes        # noqa: F401
+from numclassify._core import figurate as _figurate      # noqa: F401
+from numclassify._core import digital as _digital       # noqa: F401
+from numclassify._core import recreational as _recreational  # noqa: F401
+from numclassify._core import divisors as _divisors      # noqa: F401
+from numclassify._core import sequences as _sequences     # noqa: F401
+from numclassify._core import powers as _powers        # noqa: F401
+from numclassify._core import number_theory as _number_theory # noqa: F401
+from numclassify._core import combinatorial as _combinatorial # noqa: F401
+
+# --- Re-export key functions at top level ---
+from numclassify._core.primes import is_prime         # noqa: F401
+from numclassify._core.digital import is_armstrong    # noqa: F401
+from numclassify._core.divisors import is_perfect     # noqa: F401
+from numclassify._registry import register             # noqa: F401
+from numclassify._registry import (                   # noqa: F401
+    get_all_properties,
+    get_true_properties,
+    print_properties,
+    find_in_range,
+    find_all_in_range,
+    count_properties,
+    most_special_in_range,
+)
+
+# ---------------------------------------------------------------------------
+# Dynamic attribute fallback — allows nc.<any_registered_type>() to work
+# ---------------------------------------------------------------------------
+
+def __getattr__(name: str):
+    """Fallback: look up *name* in the global registry as a normalised key."""
+    from numclassify._registry import REGISTRY, _normalize
+
+    key = _normalize(name)
+    if key in REGISTRY:
+        return REGISTRY[key].func
+    raise AttributeError(f"module 'numclassify' has no attribute {name!r}")
+
+
+# ---------------------------------------------------------------------------
+# New features
+# ---------------------------------------------------------------------------
+
+def classify(n: int) -> dict:
+    """
+    Returns a summary dict for a single integer.
+
+    Returns
+    -------
+    {
+        "number": n,
+        "true_properties": [list of property names that are True],
+        "score": int,   # count of True properties
+    }
+    """
+    raw = get_true_properties(n)
+    if isinstance(raw, dict):
+        true_props = [k for k, v in raw.items() if v]
+    else:
+        true_props = list(raw)
+
+    return {
+        "number": n,
+        "true_properties": true_props,
+        "score": len(true_props),
+    }
+
+
+def classify_batch(numbers: list) -> list:
+    """Returns a list of classify(n) dicts, one per number, same order."""
+    return [classify(n) for n in numbers]
+
+
+def random_number(max_n: int = 10000) -> dict:
+    """Picks a random int between 1 and max_n inclusive, returns classify(n)."""
+    import random as _random
+    n = _random.randint(1, max_n)
+    return classify(n)
+
+
+def find_by_property(start: int = 1, end: int = 1000,
+                     limit: int | None = None, **filters: bool) -> list:
+    """
+    Query numbers by property values within [start, end].
+
+    Parameters
+    ----------
+    start, end : int
+        Inclusive search range.
+    limit : int, optional
+        Stop after finding this many matches.
+    **filters : bool
+        Property name to required bool value mapping.
+
+    Returns
+    -------
+    list of int
+
+    Example
+    -------
+    find_by_property(start=1, end=1000, Perfect=True, Odious=True)
+    """
+    results = []
+    for n in range(start, end + 1):
+        if not filters:
+            results.append(n)
+        else:
+            props = get_all_properties(n)
+            if all(props.get(k) == v for k, v in filters.items()):
+                results.append(n)
+        if limit is not None and len(results) >= limit:
+            break
+    return results
+
+
+def stream(start: int, end: int):
+    """Generator. Yields classify(n) for each n in [start, end]. Memory-safe for large ranges."""
+    for n in range(start, end + 1):
+        yield classify(n)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    "__version__",
+    "is_prime",
+    "is_armstrong",
+    "is_perfect",
+    "get_all_properties",
+    "get_true_properties",
+    "print_properties",
+    "find_in_range",
+    "find_all_in_range",
+    "count_properties",
+    "most_special_in_range",
+    "classify",
+    "classify_batch",
+    "random_number",
+    "find_by_property",
+    "stream",
+]
+
+# Clean up internal names that leak into dir(nc)
+del (_primes, _figurate, _digital, _recreational,
+     _divisors, _sequences, _powers, _number_theory,
+     _combinatorial, _core, _registry)

{numclassify-0.1.1 → numclassify-0.2.1}/numclassify/_registry.py

@@ -123,6 +123,9 @@ def register(
         key = _normalize(name)
         with _REGISTRY_LOCK:
             REGISTRY[key] = entry
+            # Also register under the function's __name__ so
+            # nc.<func_name>() works via __getattr__ fallback
+            REGISTRY[_normalize(func.__name__)] = entry
             for alias in _aliases:
                 REGISTRY[_normalize(alias)] = entry
         return func

{numclassify-0.1.1 → numclassify-0.2.1}/numclassify/cli.py

@@ -21,6 +21,9 @@ info <type_name>
 
 list [--category <cat>]
     List all registered types, optionally filtered by category.
+
+compare <a> <b> [--json]
+    Compare two numbers: show shared and exclusive properties.
 """
 
 from __future__ import annotations
@@ -345,6 +348,46 @@ def cmd_list(args: argparse.Namespace) -> None:
     print()
 
 
+def cmd_compare(args: argparse.Namespace) -> None:
+    """Handle: numclassify compare <a> <b> [--json]."""
+    nc, _, _ = _lazy_import()
+
+    try:
+        a = int(args.a)
+        b = int(args.b)
+    except ValueError:
+        _die("a and b must be integers.")
+
+    props_a = set(nc.get_true_properties(a))
+    props_b = set(nc.get_true_properties(b))
+
+    shared = sorted(props_a & props_b)
+    only_a = sorted(props_a - props_b)
+    only_b = sorted(props_b - props_a)
+
+    if args.json:
+        payload = {
+            "a": a,
+            "b": b,
+            "shared": shared,
+            "only_a": only_a,
+            "only_b": only_b,
+        }
+        print(json.dumps(payload, indent=2))
+        return
+
+    header = f"Comparing {a} and {b}"
+    print(_bold(header))
+    print(_rule(len(header)))
+
+    def _fmt_list(items: List[str]) -> str:
+        return ", ".join(items) if items else "(none)"
+
+    print(f"Shared ({len(shared)}): {_fmt_list(shared)}")
+    print(f"Only in {a} ({len(only_a)}): {_fmt_list(only_a)}")
+    print(f"Only in {b} ({len(only_b)}): {_fmt_list(only_b)}")
+
+
 # ---------------------------------------------------------------------------
 # Argument parser
 # ---------------------------------------------------------------------------
@@ -475,8 +518,28 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_list.set_defaults(func=cmd_list)
 
-    return parser
+    # -- compare -------------------------------------------------------------
+    p_compare = sub.add_parser(
+        "compare",
+        help="Compare properties of two numbers side by side.",
+        description=(
+            "Show shared and exclusive properties between two integers.\n\n"
+            "Examples:\n"
+            "  numclassify compare 6 28\n"
+            "  numclassify compare 6 28 --json"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_compare.add_argument("a", help="First integer.")
+    p_compare.add_argument("b", help="Second integer.")
+    p_compare.add_argument(
+        "--json",
+        action="store_true",
+        help="Output results as JSON with keys a, b, shared, only_a, only_b.",
+    )
+    p_compare.set_defaults(func=cmd_compare)
 
+    return parser
 
 # ---------------------------------------------------------------------------
 # Entry point
@@ -500,7 +563,20 @@ def main() -> None:
         )
 
     # ------------------------------------------------------------------
-    # 2. Enable colour + Unicode only when writing to a real terminal.
+    # 2. Enable VT100 ANSI escape processing on Windows consoles.
+    #    On older Windows 10 builds and Wine, ANSI codes are printed
+    #    literally unless the console mode flag is set explicitly.
+    # ------------------------------------------------------------------
+    if sys.platform == "win32":
+        import ctypes
+        try:
+            kernel32 = ctypes.windll.kernel32
+            kernel32.SetConsoleMode(kernel32.GetStdHandle(-11), 7)
+        except Exception:
+            pass
+
+    # ------------------------------------------------------------------
+    # 3. Enable colour + Unicode only when writing to a real terminal.
     #    Subprocesses/pipes get plain ASCII — no ✓, no ─, no ANSI codes.
     # ------------------------------------------------------------------
     if sys.stdout.isatty():
@@ -522,4 +598,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()

{numclassify-0.1.1 → numclassify-0.2.1}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "numclassify"
-version = "0.1.1"
-description = "The most comprehensive Python library for number classification — 3000+ number types"
+version = "0.2.1"
+description = "The most comprehensive Python library for number classification - 3000+ number types"
 authors = [{name = "Aratrik Ghosh", email = "aratrikghosh2011@gmail.com"}]
 readme = "README.md"
 requires-python = ">=3.8"
 license = {text = "MIT"}
 keywords = ["number-theory", "mathematics", "classification", "armstrong", "prime", "figurate"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Education",
     "Intended Audience :: Science/Research",
     "Topic :: Scientific/Engineering :: Mathematics",
@@ -22,6 +22,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
@@ -29,7 +30,12 @@ classifiers = [
 [project.urls]
 Homepage = "https://github.com/aratrikghosh2011-tech/numclassify"
 Repository = "https://github.com/aratrikghosh2011-tech/numclassify"
+Documentation = "https://aratrikghosh2011-tech.github.io/numclassify/"
 Issues = "https://github.com/aratrikghosh2011-tech/numclassify/issues"
 
 [project.scripts]
-numclassify = "numclassify.cli:main"
+numclassify = "numclassify.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["numclassify"]
+include = ["numclassify/py.typed"]

numclassify-0.1.1/numclassify/__init__.py

@@ -1,63 +0,0 @@
-"""
-numclassify
-~~~~~~~~~~~
-The most comprehensive Python library for number classification.
-Importing this package triggers registration of all built-in classification
-functions via their ``@register`` decorators.
-
-Public API
-----------
-.. autosummary::
-   is_prime
-   is_armstrong
-   is_perfect
-   get_all_properties
-   get_true_properties
-   print_properties
-   find_in_range
-   find_all_in_range
-   count_properties
-   most_special_in_range
-"""
-from __future__ import annotations
-
-__version__ = "0.1.0"
-
-# --- Import all _core submodules so @register decorators fire at import time ---
-from numclassify._core import primes        # noqa: F401
-from numclassify._core import figurate      # noqa: F401
-from numclassify._core import digital       # noqa: F401
-from numclassify._core import recreational  # noqa: F401
-from numclassify._core import divisors      # noqa: F401
-from numclassify._core import sequences     # noqa: F401
-from numclassify._core import powers        # noqa: F401
-from numclassify._core import number_theory # noqa: F401
-from numclassify._core import combinatorial # noqa: F401
-
-# --- Re-export key functions at top level ---
-from numclassify._core.primes import is_prime         # noqa: F401
-from numclassify._core.digital import is_armstrong    # noqa: F401
-from numclassify._core.divisors import is_perfect     # noqa: F401
-from numclassify._registry import (                   # noqa: F401
-    get_all_properties,
-    get_true_properties,
-    print_properties,
-    find_in_range,
-    find_all_in_range,
-    count_properties,
-    most_special_in_range,
-)
-
-__all__ = [
-    "__version__",
-    "is_prime",
-    "is_armstrong",
-    "is_perfect",
-    "get_all_properties",
-    "get_true_properties",
-    "print_properties",
-    "find_in_range",
-    "find_all_in_range",
-    "count_properties",
-    "most_special_in_range",
-]