docs-validator 0.1.0__tar.gz

docs_validator-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Ramos
+
+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.

docs_validator-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: docs-validator
+Version: 0.1.0
+Summary: Brazilian document validator (CNPJ numeric and alphanumeric)
+Author: Bruno Ramos
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# docs-validator
+
+![CI](https://github.com/thinkbruno/docs-validator/actions/workflows/ci.yml/badge.svg?branch=main)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+A lightweight Python library for validating Brazilian document
+identifiers.
+
+Currently the project supports:
+
+- CNPJ (numeric)
+- **Experimental support for alphanumeric CNPJ**
+
+The project is designed with:
+
+- clean architecture
+- automated testing
+- CI/CD
+- PyPI-ready packaging
+
+---
+
+# ⚠️ About Alphanumeric CNPJ
+
+As of **2026**, there are **no alphanumeric CNPJ numbers in public
+circulation**.
+
+The future format has been announced by the Receita Federal do Brasil,
+but the official database still contains **only numeric CNPJ
+identifiers**.
+
+Therefore:
+
+⚠️ Any alphanumeric CNPJ used in this project is **only for algorithm
+testing purposes** and **does not represent a real company**.
+
+---
+
+# Experimental Validation Mode
+
+To allow experimentation with the future format, the library supports an
+**experimental validation mode**.
+
+Example:
+
+```python
+from docs_validator import validate
+
+validate("12ABC34501DE35", mode="experimental")
+```
+
+When using `mode="experimental"`:
+
+- letters **A-Z** are allowed in the first 12 positions
+- letters are converted using **base36 mapping**
+- the **same modulo‑11 check digit algorithm** is applied
+
+Mapping example:
+
+    A = 10
+    B = 11
+    ...
+    Z = 35
+
+Without experimental mode:
+
+```python
+validate("12ABC34501DE35")
+# returns False
+```
+
+---
+
+# Installation
+
+```bash
+pip install docs-validator
+```
+
+---
+
+# Usage
+
+## Validate numeric CNPJ
+
+```python
+from docs_validator import validate
+
+validate("11222333000181")
+```
+
+## Validate experimental alphanumeric CNPJ
+
+```python
+validate("12ABC34501DE35", mode="experimental")
+```
+
+## Format CNPJ
+
+```python
+from docs_validator import format_cnpj
+
+format_cnpj("11222333000181")
+```
+
+Output:
+
+    11.222.333/0001-81
+
+---
+
+# Running tests
+
+```bash
+pytest --cov=docs_validator
+```
+
+Generate HTML coverage report:
+
+```bash
+pytest --cov=docs_validator --cov-report=html
+```
+
+---
+
+# Project structure
+
+    docs-validator
+    │
+    ├── src/
+    │   └── docs_validator/
+    │
+    ├── tests/
+    │
+    ├── pyproject.toml
+    └── README.md
+
+---
+
+# Roadmap
+
+Planned features:
+
+- CPF validation
+- document generators
+- CLI interface
+- support for additional Brazilian identifiers
+- benchmarking tools
+
+---
+
+# Author
+
+Bruno Ramos
+
+LinkedIn\
+https://www.linkedin.com/in/ramosbruno90/
+
+GitHub\
+https://github.com/thinkbruno
+
+---
+
+# License
+
+MIT

docs_validator-0.1.0/README.md

@@ -0,0 +1,167 @@
+# docs-validator
+
+![CI](https://github.com/thinkbruno/docs-validator/actions/workflows/ci.yml/badge.svg?branch=main)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+A lightweight Python library for validating Brazilian document
+identifiers.
+
+Currently the project supports:
+
+- CNPJ (numeric)
+- **Experimental support for alphanumeric CNPJ**
+
+The project is designed with:
+
+- clean architecture
+- automated testing
+- CI/CD
+- PyPI-ready packaging
+
+---
+
+# ⚠️ About Alphanumeric CNPJ
+
+As of **2026**, there are **no alphanumeric CNPJ numbers in public
+circulation**.
+
+The future format has been announced by the Receita Federal do Brasil,
+but the official database still contains **only numeric CNPJ
+identifiers**.
+
+Therefore:
+
+⚠️ Any alphanumeric CNPJ used in this project is **only for algorithm
+testing purposes** and **does not represent a real company**.
+
+---
+
+# Experimental Validation Mode
+
+To allow experimentation with the future format, the library supports an
+**experimental validation mode**.
+
+Example:
+
+```python
+from docs_validator import validate
+
+validate("12ABC34501DE35", mode="experimental")
+```
+
+When using `mode="experimental"`:
+
+- letters **A-Z** are allowed in the first 12 positions
+- letters are converted using **base36 mapping**
+- the **same modulo‑11 check digit algorithm** is applied
+
+Mapping example:
+
+    A = 10
+    B = 11
+    ...
+    Z = 35
+
+Without experimental mode:
+
+```python
+validate("12ABC34501DE35")
+# returns False
+```
+
+---
+
+# Installation
+
+```bash
+pip install docs-validator
+```
+
+---
+
+# Usage
+
+## Validate numeric CNPJ
+
+```python
+from docs_validator import validate
+
+validate("11222333000181")
+```
+
+## Validate experimental alphanumeric CNPJ
+
+```python
+validate("12ABC34501DE35", mode="experimental")
+```
+
+## Format CNPJ
+
+```python
+from docs_validator import format_cnpj
+
+format_cnpj("11222333000181")
+```
+
+Output:
+
+    11.222.333/0001-81
+
+---
+
+# Running tests
+
+```bash
+pytest --cov=docs_validator
+```
+
+Generate HTML coverage report:
+
+```bash
+pytest --cov=docs_validator --cov-report=html
+```
+
+---
+
+# Project structure
+
+    docs-validator
+    │
+    ├── src/
+    │   └── docs_validator/
+    │
+    ├── tests/
+    │
+    ├── pyproject.toml
+    └── README.md
+
+---
+
+# Roadmap
+
+Planned features:
+
+- CPF validation
+- document generators
+- CLI interface
+- support for additional Brazilian identifiers
+- benchmarking tools
+
+---
+
+# Author
+
+Bruno Ramos
+
+LinkedIn\
+https://www.linkedin.com/in/ramosbruno90/
+
+GitHub\
+https://github.com/thinkbruno
+
+---
+
+# License
+
+MIT

docs_validator-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "docs-validator"
+version = "0.1.0"
+description = "Brazilian document validator (CNPJ numeric and alphanumeric)"
+authors = [{ name = "Bruno Ramos" }]
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

docs_validator-0.1.0/setup.cfg

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

docs_validator-0.1.0/src/docs_validator/__init__.py

@@ -0,0 +1,4 @@
+from .validator import validate
+from .formatter import format_cnpj
+
+__all__ = ["validate", "format_cnpj"]

docs_validator-0.1.0/src/docs_validator/dv.py

@@ -0,0 +1,15 @@
+from .utils import char_to_value
+
+WEIGHTS_FIRST = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2]
+WEIGHTS_SECOND = [6] + WEIGHTS_FIRST
+
+
+def calculate_digit(base: str, weights: list[int]) -> int:
+    total = 0
+
+    for char, weight in zip(base, weights):
+        total += char_to_value(char) * weight
+
+    remainder = total % 11
+
+    return 0 if remainder < 2 else 11 - remainder

docs_validator-0.1.0/src/docs_validator/formatter.py

@@ -0,0 +1,10 @@
+from .utils import normalize
+
+
+def format_cnpj(value: str) -> str:
+    value = normalize(value)
+
+    if len(value) != 14:
+        raise ValueError("Invalid CNPJ length")
+
+    return f"{value[:2]}.{value[2:5]}.{value[5:8]}/{value[8:12]}-{value[12:]}"

docs_validator-0.1.0/src/docs_validator/utils.py

@@ -0,0 +1,18 @@
+import re
+
+
+def normalize(value: str) -> str:
+    """
+    Remove non alphanumeric characters and uppercase value
+    """
+    return re.sub(r"[^A-Z0-9]", "", value.upper())
+
+
+def char_to_value(char: str) -> int:
+    """
+    Convert alphanumeric character to numeric value
+    """
+    if char.isdigit():
+        return int(char)
+
+    return ord(char) - 55  # A=10 ... Z=35

docs_validator-0.1.0/src/docs_validator/validator.py

@@ -0,0 +1,17 @@
+from .utils import normalize
+from .dv import calculate_digit, WEIGHTS_FIRST, WEIGHTS_SECOND
+
+
+def validate(cnpj: str) -> bool:
+    cnpj = normalize(cnpj)
+
+    if len(cnpj) != 14:
+        return False
+
+    base = cnpj[:12]
+    dv = cnpj[12:]
+
+    digit1 = calculate_digit(base, WEIGHTS_FIRST)
+    digit2 = calculate_digit(base + str(digit1), WEIGHTS_SECOND)
+
+    return dv == f"{digit1}{digit2}"

docs_validator-0.1.0/src/docs_validator.egg-info/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: docs-validator
+Version: 0.1.0
+Summary: Brazilian document validator (CNPJ numeric and alphanumeric)
+Author: Bruno Ramos
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# docs-validator
+
+![CI](https://github.com/thinkbruno/docs-validator/actions/workflows/ci.yml/badge.svg?branch=main)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+A lightweight Python library for validating Brazilian document
+identifiers.
+
+Currently the project supports:
+
+- CNPJ (numeric)
+- **Experimental support for alphanumeric CNPJ**
+
+The project is designed with:
+
+- clean architecture
+- automated testing
+- CI/CD
+- PyPI-ready packaging
+
+---
+
+# ⚠️ About Alphanumeric CNPJ
+
+As of **2026**, there are **no alphanumeric CNPJ numbers in public
+circulation**.
+
+The future format has been announced by the Receita Federal do Brasil,
+but the official database still contains **only numeric CNPJ
+identifiers**.
+
+Therefore:
+
+⚠️ Any alphanumeric CNPJ used in this project is **only for algorithm
+testing purposes** and **does not represent a real company**.
+
+---
+
+# Experimental Validation Mode
+
+To allow experimentation with the future format, the library supports an
+**experimental validation mode**.
+
+Example:
+
+```python
+from docs_validator import validate
+
+validate("12ABC34501DE35", mode="experimental")
+```
+
+When using `mode="experimental"`:
+
+- letters **A-Z** are allowed in the first 12 positions
+- letters are converted using **base36 mapping**
+- the **same modulo‑11 check digit algorithm** is applied
+
+Mapping example:
+
+    A = 10
+    B = 11
+    ...
+    Z = 35
+
+Without experimental mode:
+
+```python
+validate("12ABC34501DE35")
+# returns False
+```
+
+---
+
+# Installation
+
+```bash
+pip install docs-validator
+```
+
+---
+
+# Usage
+
+## Validate numeric CNPJ
+
+```python
+from docs_validator import validate
+
+validate("11222333000181")
+```
+
+## Validate experimental alphanumeric CNPJ
+
+```python
+validate("12ABC34501DE35", mode="experimental")
+```
+
+## Format CNPJ
+
+```python
+from docs_validator import format_cnpj
+
+format_cnpj("11222333000181")
+```
+
+Output:
+
+    11.222.333/0001-81
+
+---
+
+# Running tests
+
+```bash
+pytest --cov=docs_validator
+```
+
+Generate HTML coverage report:
+
+```bash
+pytest --cov=docs_validator --cov-report=html
+```
+
+---
+
+# Project structure
+
+    docs-validator
+    │
+    ├── src/
+    │   └── docs_validator/
+    │
+    ├── tests/
+    │
+    ├── pyproject.toml
+    └── README.md
+
+---
+
+# Roadmap
+
+Planned features:
+
+- CPF validation
+- document generators
+- CLI interface
+- support for additional Brazilian identifiers
+- benchmarking tools
+
+---
+
+# Author
+
+Bruno Ramos
+
+LinkedIn\
+https://www.linkedin.com/in/ramosbruno90/
+
+GitHub\
+https://github.com/thinkbruno
+
+---
+
+# License
+
+MIT

docs_validator-0.1.0/src/docs_validator.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/docs_validator/__init__.py
+src/docs_validator/dv.py
+src/docs_validator/formatter.py
+src/docs_validator/utils.py
+src/docs_validator/validator.py
+src/docs_validator.egg-info/PKG-INFO
+src/docs_validator.egg-info/SOURCES.txt
+src/docs_validator.egg-info/dependency_links.txt
+src/docs_validator.egg-info/top_level.txt
+tests/test_validator.py

docs_validator-0.1.0/src/docs_validator.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

docs_validator-0.1.0/src/docs_validator.egg-info/top_level.txt

@@ -0,0 +1 @@
+docs_validator

docs_validator-0.1.0/tests/test_validator.py

@@ -0,0 +1,13 @@
+from cnpj_validator import validate
+
+
+def test_valid_cnpj():
+    assert validate("11222333000181") is True
+
+
+def test_invalid_cnpj():
+    assert validate("11222333000182") is False
+
+
+def test_formatted_cnpj():
+    assert validate("11.222.333/0001-81") is True