Metadata-Version: 2.4
Name: nepalpy
Version: 1.2.1
Summary: Nepali name generator, surname and caste/ethnic group utilities
Home-page: https://github.com/mrsushilshrestha/nepalpy
Author: Sushil Shrestha
Author-email: mrsushilshresthaofficial@gmail.com
License: MIT
Project-URL: LinkedIn, https://www.linkedin.com/in/mrsushilshresthaofficial/
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# nepalpy 🇳🇵

**Nepali Name & Caste Generator** – A lightweight, zero-dependency Python library to generate realistic Nepali names, surnames (castes), and caste/ethnic group categories.

`nepalpy` is designed for developers, researchers, and students who need **realistic Nepali demographic data** for testing, simulations, analytics, or educational projects.

---

## ✨ Why nepalpy?

Nepali names and caste systems are **culturally rich and diverse**, but most fake-data libraries don’t support Nepal properly.

`nepalpy` fills this gap by providing:

* Authentic Nepali first names (male & female)
* Large, curated caste/surname datasets
* Accurate caste category mapping
* Simple, fast, dependency-free API

---

## 🚀 Features

* ✅ Generate random Nepali first names
* ✅ Generate male, female, or mixed names
* ✅ Filter names by starting or ending letters
* ✅ Generate surnames (castes)
* ✅ Generate full names (first + last)
* ✅ Access **100+ Nepali castes/surnames**
* ✅ Identify caste category:

  * khas-arya
  * janajati
  * newar
  * dalit
  * madhesi
* ✅ All outputs normalized to **lowercase**
* ✅ Zero external dependencies

---

## 📦 Installation

```bash
pip install nepalpy
```

Python 3.7+ supported.

---

## 🧠 Basic Usage

```python
from nepalpy.name import name, last_name, full_name, cast, cast_category
```

---

## 🧑 First Name Generator

### Generate random names (mixed)

```python
name(5)
```

**Output:**

```text
['sushil', 'dibisha', 'rama', 'gita', 'dipesh']
```

---

### Generate male & female names separately

```python
name(male=3, female=2)
```

**Output:**

```text
['ram', 'suman', 'binod', 'gita', 'sita']
```

---

## 🔠 Filter Names

### Names starting with a letter

```python
name_start_with('s', count=5)
```

**Output:**

```text
['suresh', 'suman', 'sunita', 'sagar', 'sita']
```

---

### Names ending with a letter

```python
name_end_with('a', count=5)
```

**Output:**

```text
['gita', 'sita', 'anita', 'rekha', 'laxmita']
```

---

## 👨‍👩‍👧 Surname / Caste Generator

### Generate a random caste (surname)

```python
last_name()
```

**Output:**

```text
'maharjan'
```

---

### Generate multiple castes

```python
cast(5)
```

**Output:**

```text
['thapa', 'kami', 'tamang', 'shrestha', 'yadav']
```

---

## 🧾 Full Name Generator

```python
full_name()
```

**Output:**

```text
'sushil shrestha'
```

---

## 🏷️ Caste Category Detection

Identify the caste/ethnic group for a given surname.

```python
cast_category('Kami')
```

**Output:**

```text
'dalit'
```

More examples:

```python
cast_category('Thapa')      # khas-arya
cast_category('Maharjan')   # janajati
cast_category('Yadav')      # madhesi
```

---

## 📚 Supported Caste Categories

* **khas-arya** (bahun, chhetri, thakuri, sanyasi)
* **janajati** (tamang, gurung, magar, rai, limbu, etc.)
* **newar** (shrestha, maharjan, sakya, bajracharya, etc.)
* **dalit** (kami, damai, sarki, bishwokarma, etc.)
* **madhesi** (yadav, kurmi, teli, chamar, etc.)

All mappings are configurable and expandable.

---

## 🧪 Use Cases

* Fake data generation for Nepali apps
* Backend testing & QA automation
* Academic & demographic simulations
* Machine learning datasets
* Forms & validation testing
* Government / NGO software prototyping

---

## 🛠️ Design Philosophy

* 🔹 Simple API
* 🔹 Human-readable outputs
* 🔹 Culturally aware data
* 🔹 No third-party dependencies
* 🔹 Easy to extend

---

## 🤝 Contributing

Contributions are welcome!

You can help by:

* Adding more names
* Improving caste mappings
* Adding aliases & spelling variants
* Writing tests
* Improving documentation

---

## 📄 License

MIT License © 2026

---

## 🇳🇵 Made for Nepal

Built with ❤️ to support Nepali developers and researchers.
