# LuhnCheck
A Python package to validate identification numbers using the Luhn algorithm
with additional optional checks.
## Overview
The Luhn algorithm or Luhn formula, also known as the "modulus 10" or "mod 10"
algorithm, named after its creator, IBM scientist Hans Peter Luhn, is a simple
checksum formula used to validate a variety of identification numbers, such as:
- US National Provider Identifier numbers.
- Canadian Social Insurance Numbers.
- Saudi Arabia National and Resident ID numbers.
- South African ID numbers.
- Swedish National identification numbers.
- Swedish Corporate Identity Numbers (OrgNr).
- Greek Social Security Numbers (ΑΜΚΑ).
- Credit card numbers.
- IMEI numbers.
The algorithm is in the public domain and is in wide use today. It was designed
to protect against accidental errors. Most credit cards and many government
identification numbers use the algorithm to distinguish valid numbers from
mistyped or otherwise incorrect numbers.
## Features
- Simple API to validate numbers based on the Luhn algorithm.
- Extended validation to cover number length and prefix(es).
- Can validate numbers containing hyphens or spaces.
- Works on Python 3.8+ with zero dependencies.
- Thoroughly tested with 100% test coverage.
## Installation
To install using `pip`, run:
```shell
pip install luhncheck
```
## Usage Examples
```pycon
>>> from luhncheck import is_luhn
>>> # Simple checksum validation
>>> is_luhn("1101798278")
True
>>> # Additional check for length (9 digits)
>>> is_luhn("1101798278", 9)
False
>>> # Additional checks for prefix (either 1 or 2)
>>> is_luhn("1101798278", 10, ["1", "2"])
True
>>> # Validate numbers containing hyphens
>>> is_luhn("01-055102-109831-4", None, "01")
True
```
## API Reference
### <kbd>function</kbd> `is_luhn`
```python
is_luhn(
number: str,
length: int | None = None,
prefix: str | list[str] | None = None
) -> bool
```
Validate checksum and format of an identification number based on the Luhn
algorithm.
**Args:**
- **`number`**: Identification number to validate.
- **`length`**: How many digits the number must contain. (The default is `None`,
which implies skipping the length check).
- **`prefix`**: Exact digit(s) the number must start with. When a list of digits
is provided, one of the values must match. (The default is `None`, which
implies skipping the prefix check).
**Returns:**
- `True` when the number is valid; otherwise, `False`.
## License
This project is licensed under the terms of the MIT license.
Raw data
{
"_id": null,
"home_page": "https://github.com/dralshehri/luhncheck",
"name": "luhncheck",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "luhn,validator,validation,numbers,identification,imei,credit-card",
"author": "Mohammed Alshehri",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/c6/ce/7c7464f1faafcba5e9d8c9b693be4c42e51a90d787f3c5fb826f6e680d57/luhncheck-2.2.0.tar.gz",
"platform": null,
"description": "# LuhnCheck\n\nA Python package to validate identification numbers using the Luhn algorithm\nwith additional optional checks.\n\n## Overview\n\nThe Luhn algorithm or Luhn formula, also known as the \"modulus 10\" or \"mod 10\"\nalgorithm, named after its creator, IBM scientist Hans Peter Luhn, is a simple\nchecksum formula used to validate a variety of identification numbers, such as:\n\n- US National Provider Identifier numbers.\n- Canadian Social Insurance Numbers.\n- Saudi Arabia National and Resident ID numbers.\n- South African ID numbers.\n- Swedish National identification numbers.\n- Swedish Corporate Identity Numbers (OrgNr).\n- Greek Social Security Numbers (\u0391\u039c\u039a\u0391).\n- Credit card numbers.\n- IMEI numbers.\n\nThe algorithm is in the public domain and is in wide use today. It was designed\nto protect against accidental errors. Most credit cards and many government\nidentification numbers use the algorithm to distinguish valid numbers from\nmistyped or otherwise incorrect numbers.\n\n## Features\n\n- Simple API to validate numbers based on the Luhn algorithm.\n- Extended validation to cover number length and prefix(es).\n- Can validate numbers containing hyphens or spaces.\n- Works on Python 3.8+ with zero dependencies.\n- Thoroughly tested with 100% test coverage.\n\n## Installation\n\nTo install using `pip`, run:\n\n```shell\npip install luhncheck\n```\n\n## Usage Examples\n\n```pycon\n>>> from luhncheck import is_luhn\n\n>>> # Simple checksum validation\n>>> is_luhn(\"1101798278\")\nTrue\n\n>>> # Additional check for length (9 digits)\n>>> is_luhn(\"1101798278\", 9)\nFalse\n\n>>> # Additional checks for prefix (either 1 or 2)\n>>> is_luhn(\"1101798278\", 10, [\"1\", \"2\"])\nTrue\n\n>>> # Validate numbers containing hyphens\n>>> is_luhn(\"01-055102-109831-4\", None, \"01\")\nTrue\n```\n\n## API Reference\n\n### <kbd>function</kbd> `is_luhn`\n\n```python\nis_luhn(\n number: str,\n length: int | None = None,\n prefix: str | list[str] | None = None\n) -> bool\n```\n\nValidate checksum and format of an identification number based on the Luhn\nalgorithm.\n\n**Args:**\n\n- **`number`**: Identification number to validate.\n- **`length`**: How many digits the number must contain. (The default is `None`,\n which implies skipping the length check).\n- **`prefix`**: Exact digit(s) the number must start with. When a list of digits\n is provided, one of the values must match. (The default is `None`, which\n implies skipping the prefix check).\n\n**Returns:**\n\n- `True` when the number is valid; otherwise, `False`.\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple validator for identification numbers based on the Luhn algorithm",
"version": "2.2.0",
"project_urls": {
"Homepage": "https://github.com/dralshehri/luhncheck"
},
"split_keywords": [
"luhn",
"validator",
"validation",
"numbers",
"identification",
"imei",
"credit-card"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "63755b8d0f5af760f9d5afbfd99b990d87b7ec8b58cec47d8cb18f96f4811856",
"md5": "e8a632d149cb75e683e590cb62b3fcbf",
"sha256": "bc5964d04bfd38541e580b4c83e42ba2b0b3f72284cd15dd56955f13a96a0479"
},
"downloads": -1,
"filename": "luhncheck-2.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e8a632d149cb75e683e590cb62b3fcbf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 4380,
"upload_time": "2024-01-19T18:42:18",
"upload_time_iso_8601": "2024-01-19T18:42:18.131331Z",
"url": "https://files.pythonhosted.org/packages/63/75/5b8d0f5af760f9d5afbfd99b990d87b7ec8b58cec47d8cb18f96f4811856/luhncheck-2.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c6ce7c7464f1faafcba5e9d8c9b693be4c42e51a90d787f3c5fb826f6e680d57",
"md5": "57c74f74122fe1d2ca665f94a2a315d1",
"sha256": "45fdd6f9ff920ebb5e245a36160ce12a4933fa1d0acc788cf91ac02fa78218af"
},
"downloads": -1,
"filename": "luhncheck-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "57c74f74122fe1d2ca665f94a2a315d1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7428,
"upload_time": "2024-01-19T18:42:19",
"upload_time_iso_8601": "2024-01-19T18:42:19.600260Z",
"url": "https://files.pythonhosted.org/packages/c6/ce/7c7464f1faafcba5e9d8c9b693be4c42e51a90d787f3c5fb826f6e680d57/luhncheck-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-19 18:42:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dralshehri",
"github_project": "luhncheck",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "luhncheck"
}
JSON
