Metadata-Version: 2.4
Name: uk-company-number
Version: 1.0.0
Summary: Validate, format, and identify UK Companies House company numbers
Project-URL: Homepage, https://borsch.ai
Project-URL: Repository, https://github.com/borschai/uk-company-number
Project-URL: Documentation, https://github.com/borschai/uk-company-number#readme
Author-email: "BORSCH.AI" <hello@borsch.ai>
License-Expression: MIT
Keywords: business,companies-house,company-number,uk,validation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# uk-company-number

Validate, format, and identify UK Companies House company numbers in Python.

> Built by [BORSCH.AI](https://borsch.ai) — UK Business Intelligence Platform
> covering 5.9M companies with AI-powered risk scores and 50M+ government signals.

Also available as an [npm package](https://www.npmjs.com/package/uk-company-number) for Node.js/TypeScript.

## Installation

```bash
pip install uk-company-number
```

## Quick Start

```python
from uk_company_number import validate, parse, format_number

# Validate
validate("12345678")   # True
validate("SC123456")   # True
validate("XXXX")       # False

# Parse into structured info
info = parse("SC123456")
print(info.jurisdiction)       # "scotland"
print(info.jurisdiction_name)  # "Scotland"
print(info.type)               # "ltd"
print(info.type_name)          # "Private Limited Company"

# Format to canonical form
format_number("1234")      # "00001234"
format_number("sc123456")  # "SC123456"
```

## API

### `parse(number: str) -> CompanyNumberInfo | None`

Parse a company number into structured information. Returns `None` for invalid numbers.

```python
info = parse("OC301234")
info.number           # "OC301234"
info.prefix           # "OC"
info.numeric_part     # "301234"
info.jurisdiction     # "england-wales"
info.jurisdiction_name  # "England & Wales"
info.type             # "llp"
info.type_name        # "Limited Liability Partnership"
```

### `validate(number: str) -> bool`

Check if a string is a valid UK company number format.

```python
validate("12345678")  # True
validate("SC123456")  # True
validate("00000000")  # False
validate("")          # False
```

### `format_number(number: str) -> str | None`

Format a company number to its canonical (zero-padded, uppercase) form.

```python
format_number("1234")      # "00001234"
format_number("sc123456")  # "SC123456"
format_number("invalid")   # None
```

### `get_jurisdiction(number: str) -> str | None`

Get the jurisdiction for a company number.

```python
get_jurisdiction("12345678")  # "england-wales"
get_jurisdiction("SC123456")  # "scotland"
get_jurisdiction("NI654321")  # "northern-ireland"
```

### `get_type(number: str) -> str | None`

Get the company type for a company number.

```python
get_type("12345678")  # "ltd"
get_type("OC301234")  # "llp"
get_type("LP123456")  # "lp"
```

### `get_prefix(number: str) -> str | None`

Get the prefix from a company number.

```python
get_prefix("SC123456")  # "SC"
get_prefix("12345678")  # ""
```

### `equals(a: str, b: str) -> bool`

Check if two company numbers refer to the same company (handles different formatting).

```python
equals("1234", "00001234")      # True
equals("sc123456", "SC123456")  # True
equals("1234", "5678")          # False
```

### `prefixes() -> list[dict]`

Get all known prefixes and their descriptions.

```python
for p in prefixes():
    print(f"{p['prefix']}: {p['type_name']} ({p['jurisdiction_name']})")
```

## Supported Prefixes

| Prefix | Type | Jurisdiction |
|--------|------|-------------|
| *(none)* | Private Limited Company | England & Wales |
| SC | Private Limited Company | Scotland |
| NI | Private Limited Company | Northern Ireland |
| OC | Limited Liability Partnership | England & Wales |
| SO | Limited Liability Partnership | Scotland |
| NC | Limited Liability Partnership | Northern Ireland |
| LP | Limited Partnership | England & Wales |
| SL | Limited Partnership | Scotland |
| FC | Overseas Company | United Kingdom |
| SE | Societas Europaea | United Kingdom |
| CE | Community Interest Company | England & Wales |
| OE | Overseas Entity | United Kingdom |
| ... | *and 15 more* | |

## Data Types

```python
@dataclass
class CompanyNumberInfo:
    number: str             # Canonical form, e.g. "SC123456"
    prefix: str             # Prefix, e.g. "SC"
    numeric_part: str       # Digits only, e.g. "123456"
    jurisdiction: str       # e.g. "scotland"
    jurisdiction_name: str  # e.g. "Scotland"
    type: str               # e.g. "ltd"
    type_name: str          # e.g. "Private Limited Company"
```

## Data Source

Based on the official Companies House company number format specification.
Full company data available at [borsch.ai](https://borsch.ai).

## License

MIT
