Metadata-Version: 2.4
Name: tamil-names
Version: 0.1.0
Summary: A professional Python utility using a CSV backend to generate random and authentic Tamil names.
Author-email: Satya <satya@example.com>
Project-URL: Homepage, https://github.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# tamil-names 🌟

A professional, high-utility Python package designed to generate authentic and culturally accurate Tamil names. Powered entirely by a structured, hand-curated CSV dataset containing 566 verified names—eliminating unpredictable web-scraped content.

## Key Features
* **Zero Dependencies**: Built strictly using Python's native ecosystem libraries (`csv`, `random`, `pathlib`).
* **Dual Script Capability**: Automatically formats text in native Tamil Unicode script (`தமிழ்`) or phonetic English transliteration (`English`).
* **Granular Filters**: Extract specific mock data based on gender identifiers (`male`, `female`, or mixed `any`).
* **Initial Formatter Engine**: Applies authentic localized structural rules using matching string constraints for prefixes and suffixes.

---

## Installation

### Local Workspace Setup
Install the utility inside your environment in active development mode:
```bash
pip install -e ./tamilnames --break-system-packages
```

### Future Production Release
Once published to PyPI, developers can install it globally via:
```bash
pip install tamil-names
```

---

## API Reference & Usage Guide

### 1. `get_name(gender="any", script="english")`
Generates a raw string corresponding to a random entry inside the master dataset.

```python
import tamilnames

# Generate a male name in native Tamil script
boy_name = tamilnames.get_name(gender="male", script="tamil")
print(boy_name)  # Output: செழியன்

# Generate a female name in English script
girl_name = tamilnames.get_name(gender="female", script="english")
print(girl_name)  # Output: Amudha

# Pull any name in English script
random_name = tamilnames.get_name()
print(random_name)  # Output: Kavin
```

### 2. `get_name_with_initial(initial, gender="any", script="english", trailing=False)`
Appends or prepends localized structural initials to names using appropriate script spacing conventions.

```python
import tamilnames

# 1. Standard English Prefix formatting (Format: Initial. Name)
print(tamilnames.get_name_with_initial(initial="S", gender="male", script="english"))
# Output: S. Anbu

# 2. Traditional Tamil Suffix formatting (Format: Name Initial - no periods used)
print(tamilnames.get_name_with_initial(initial="அ", gender="female", script="tamil", trailing=True))
# Output: ஓவியா அ
```

---

## Database Architecture
The backend is driven by a single consolidated, immutable configuration asset: `src/tamilnames/data/names.csv`.
* **Total Dataset**: 566 Records
* **Male Entries**: 291 Names
* **Female Entries**: 275 Names

---

## License
This library is open-source software distributed under the terms of the [MIT License](LICENSE).
