py-nuban 0.1.0__tar.gz

py_nuban-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+*secret.py
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

py_nuban-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pogbe Emmanuel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_nuban-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: py-nuban
+Version: 0.1.0
+Summary: Nigerian Bank Account Number prediction. Get a list of possible Nigerian banks based on an account number
+Author-email: Emmanuel Pogbe <mauyonpogbe@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/emmanuel-pogbe/py-nuban
+Project-URL: Documentation, https://github.com/emmanuel-pogbe/py-nuban#readme
+Project-URL: Bug Tracker, https://github.com/emmanuel-pogbe/py-nuban/issues
+Keywords: nuban,nigeria,bank,account-number,fintech,paystack,guess-bank
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# py-nuban
+
+Lightweight Python utilities to detect possible Nigerian banks for a given
+Nigerian Bank Account Number. Useful for validation, or bank account suggestions in payment flows.
+
+## Installation
+
+Install from PyPI when published:
+
+		pip install py-nuban
+
+Or install for development from the repository root:
+
+		pip install -e .
+
+## Quick start
+
+```python
+from py_nuban import get_possible_banks
+
+banks = get_possible_banks("1901880678")
+print(banks)  # e.g. [('033', 'United Bank for Africa'), ('044', 'Access Bank Nigeria')]
+```
+
+## What this package does
+
+- Validates a 10-digit NUBAN account number (type and length checks).
+- Runs the NUBAN checksum algorithm against all known bank codes and
+	returns the banks whose code+serial produce the same check digit.
+- Adds simple heuristics for phone-linked accounts and Moniepoint-style
+	accounts so those non-standard account numbers are also considered.
+- Filters results by a manually-assigned `popularity` score to surface
+	commonly used banks first.
+
+## NUBAN algorithm
+
+To validate a Nigerian bank account number, the system uses the official NUBAN check-digit algorithm. Here's how it works:
+The account number consists of a bank code, a serial number(the first 9 digits of an account number), and a check digit(the last digit of an account number). Because Nigerian banks use bank codes of different lengths (3, 5, or 6 digits), the code first normalizes every bank code to a standard format:
+
+3-digit codes get padded with 000 at the front.
+5-digit codes get a 9 added at the front.
+6-digit codes are used as-is.
+
+This normalized bank code is then combined with the serial number portion of the account to form a 15-character string. Each of these 15 digits is multiplied by a specific weight from this sequence:
+
+`[3, 7, 3, 3, 7, 3, 3, 7, 3, 3, 7, 3, 3, 7, 3]`
+
+All the results are added together. The system then calculates what the correct check digit should be (using modulo 10 arithmetic). If the calculated check digit matches the one provided in the account number, the NUBAN is considered valid for that bank.
+This process is repeated across all known banks until a match is found. The result is a reliable way to verify that an account number is correctly formed for its issuing bank.
+
+Example (demo):
+
+```python
+# account: 1901880678
+# serial = '190188067'  (first 9 digits)
+# check  = '8'          (last digit)
+from py_nuban import get_possible_banks
+print(get_possible_banks('1901880678'))
+# Example output (depends on the bundled bank data):
+# [('033', 'United Bank for Africa'), ('044', 'Access Bank Nigeria')]
+```
+
+## Limitations and how this package helps
+
+- Many new or smaller microfinance/payment institutions sometimes use non-standard codes 
+    and algorithms to generate their account numbers.
+    That means the NUBAN check alone can miss or misidentify such accounts.
+- To reduce false positives and surface useful results we:
+	- Add simple prefix checks (common phone-number prefixes) to detect
+		phone-linked accounts and include microfinance providers where
+		applicable.
+	- Use a manual `popularity` numeric field per bank in the bundled data to
+		filter out rarely-used entries. This is a pragmatic heuristic to make
+		results more useful in real apps; it is not a guarantee of correctness.
+
+These heuristics make the library more practical in production, but they
+also introduce opinionated filtering — see the next section.
+
+## Accuracy and safety notes
+
+- Results are a best-effort list of candidate banks, not absolute
+	guarantees. Always treat matches as suggestions and confirm with a
+	reliable resolver service (like Korapay) or the bank when accuracy is critical.
+    You should also ideally provide a fallback for the user to select the bank they use manually
+
+## Contributing
+
+Contributions welcome. Please open an issue for data updates, bug reports,
+or feature requests. Include tests and small focused changes. Add a unit
+test under `tests/` and update documentation as needed.
+
+## Testing & CI
+
+- Run the small test harness included in `tests/test_main.py`:
+
+## License
+
+This project is MIT licensed — see the `LICENSE` file for details.
+

py_nuban-0.1.0/README.md

@@ -0,0 +1,99 @@
+# py-nuban
+
+Lightweight Python utilities to detect possible Nigerian banks for a given
+Nigerian Bank Account Number. Useful for validation, or bank account suggestions in payment flows.
+
+## Installation
+
+Install from PyPI when published:
+
+		pip install py-nuban
+
+Or install for development from the repository root:
+
+		pip install -e .
+
+## Quick start
+
+```python
+from py_nuban import get_possible_banks
+
+banks = get_possible_banks("1901880678")
+print(banks)  # e.g. [('033', 'United Bank for Africa'), ('044', 'Access Bank Nigeria')]
+```
+
+## What this package does
+
+- Validates a 10-digit NUBAN account number (type and length checks).
+- Runs the NUBAN checksum algorithm against all known bank codes and
+	returns the banks whose code+serial produce the same check digit.
+- Adds simple heuristics for phone-linked accounts and Moniepoint-style
+	accounts so those non-standard account numbers are also considered.
+- Filters results by a manually-assigned `popularity` score to surface
+	commonly used banks first.
+
+## NUBAN algorithm
+
+To validate a Nigerian bank account number, the system uses the official NUBAN check-digit algorithm. Here's how it works:
+The account number consists of a bank code, a serial number(the first 9 digits of an account number), and a check digit(the last digit of an account number). Because Nigerian banks use bank codes of different lengths (3, 5, or 6 digits), the code first normalizes every bank code to a standard format:
+
+3-digit codes get padded with 000 at the front.
+5-digit codes get a 9 added at the front.
+6-digit codes are used as-is.
+
+This normalized bank code is then combined with the serial number portion of the account to form a 15-character string. Each of these 15 digits is multiplied by a specific weight from this sequence:
+
+`[3, 7, 3, 3, 7, 3, 3, 7, 3, 3, 7, 3, 3, 7, 3]`
+
+All the results are added together. The system then calculates what the correct check digit should be (using modulo 10 arithmetic). If the calculated check digit matches the one provided in the account number, the NUBAN is considered valid for that bank.
+This process is repeated across all known banks until a match is found. The result is a reliable way to verify that an account number is correctly formed for its issuing bank.
+
+Example (demo):
+
+```python
+# account: 1901880678
+# serial = '190188067'  (first 9 digits)
+# check  = '8'          (last digit)
+from py_nuban import get_possible_banks
+print(get_possible_banks('1901880678'))
+# Example output (depends on the bundled bank data):
+# [('033', 'United Bank for Africa'), ('044', 'Access Bank Nigeria')]
+```
+
+## Limitations and how this package helps
+
+- Many new or smaller microfinance/payment institutions sometimes use non-standard codes 
+    and algorithms to generate their account numbers.
+    That means the NUBAN check alone can miss or misidentify such accounts.
+- To reduce false positives and surface useful results we:
+	- Add simple prefix checks (common phone-number prefixes) to detect
+		phone-linked accounts and include microfinance providers where
+		applicable.
+	- Use a manual `popularity` numeric field per bank in the bundled data to
+		filter out rarely-used entries. This is a pragmatic heuristic to make
+		results more useful in real apps; it is not a guarantee of correctness.
+
+These heuristics make the library more practical in production, but they
+also introduce opinionated filtering — see the next section.
+
+## Accuracy and safety notes
+
+- Results are a best-effort list of candidate banks, not absolute
+	guarantees. Always treat matches as suggestions and confirm with a
+	reliable resolver service (like Korapay) or the bank when accuracy is critical.
+    You should also ideally provide a fallback for the user to select the bank they use manually
+
+## Contributing
+
+Contributions welcome. Please open an issue for data updates, bug reports,
+or feature requests. Include tests and small focused changes. Add a unit
+test under `tests/` and update documentation as needed.
+
+## Testing & CI
+
+- Run the small test harness included in `tests/test_main.py`:
+
+## License
+
+This project is MIT licensed — see the `LICENSE` file for details.
+

py_nuban-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel", "setuptools_scm[toml]>=6.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "py-nuban"
+dynamic = ["version"]
+description = "Nigerian Bank Account Number prediction. Get a list of possible Nigerian banks based on an account number"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Emmanuel Pogbe", email = "mauyonpogbe@gmail.com"}
+]
+keywords = ["nuban", "nigeria", "bank", "account-number", "fintech", "paystack", "guess-bank"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "black",
+    "ruff",
+    "mypy",
+    "twine",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/emmanuel-pogbe/py-nuban"
+"Documentation" = "https://github.com/emmanuel-pogbe/py-nuban#readme"
+"Bug Tracker" = "https://github.com/emmanuel-pogbe/py-nuban/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["py_nuban*"]
+
+[tool.setuptools.package-data]
+"py_nuban" = ["*.json"]   # Important: This includes your banks.json
+
+[tool.setuptools_scm]
+write_to = "src/py_nuban/_version.py"

py_nuban-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_nuban-0.1.0/src/py_nuban/__init__.py

@@ -0,0 +1,8 @@
+"""
+py-nuban: Nigerian bank account number validator and bank detector.
+"""
+
+from .main import get_possible_banks, get_set_of_possible_codes
+
+__version__ = "0.1.0"
+__all__ = ["get_possible_banks", "get_set_of_possible_codes"]

py_nuban-0.1.0/src/py_nuban/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = 'g76e45f1fd'