Metadata-Version: 2.1
Name: tanzania-locations
Version: 1.5.0
Summary: Tanzania regions and districts package
Home-page: https://github.com/yourusername/tanzania-locations
Author: Cornel Mtavangu
Author-email: mtavangucornel@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# Tanzania Locations 🗺️

A lightweight Python package providing **Tanzania regions and districts** for easy integration into **Django forms**, scripts, or any Python project. Perfect for building **dynamic dependent dropdowns** for location selection.


## ⚡ Installation

Install via PyPI:

```bash
pip install tanzania-locations
```


---

## 🐍 Quick Usage

```python
from tanzania_locations import get_regions, get_districts

# List all regions
regions = get_regions()
print(regions)
# ['Arusha', 'Dar es Salaam', 'Dodoma', 'Mwanza', ...]

# List districts for a region
districts = get_districts("Dar es Salaam")
print(districts)
# ['Ilala', 'Kinondoni', 'Temeke', 'Ubungo', 'Kigamboni']
```

---

## Django Integration

### 1️⃣ `views.py`

```python
from django.shortcuts import render
from django.http import JsonResponse
from tanzania_locations import get_regions, get_districts

# Display the form with regions
def location_form(request):
    context = {
        # Convert list of regions to tuples for template
        "regions": [(r, r) for r in get_regions()]
    }
    return render(request, "app/location_form.html", context)

# Return districts as JSON for a given region
def load_districts(request):
    region = request.GET.get("region")
    districts_data = get_districts(region)
    districts = districts_data['districts']
    return JsonResponse({"districts": districts})
```

### 2️⃣ `urls.py`

```python
from django.urls import path,include
from . import views

urlpatterns = [
    path("", views.location_form, name="location_form"),
    path("ajax/load-districts/", views.load_districts, name="load_districts"),
]
```

### 3️⃣ `location_form.html`

```html
<form method="post">
    {% csrf_token %}
    <label for="region">Region</label><br>
    <select id="region" name="region">
        <option value="">-- Select Region --</option>
        {% for value, label in regions %}
            <option value="{{ value }}">{{ label }}</option>
        {% endfor %}
    </select>

    <br><br>

    <label for="district">District</label><br>
    <select id="district" name="district">
        <option value="">-- Select District --</option>
    </select>

    <br><br>
    <button type="submit">Submit</button>
</form>

<script>
document.addEventListener("DOMContentLoaded", function () {
    const regionSelect = document.getElementById("region");
    const districtSelect = document.getElementById("district");

    regionSelect.addEventListener("change", function () {
        const region = this.value;
        districtSelect.innerHTML = '<option value="">Loading...</option>';

        if (!region) {
            districtSelect.innerHTML = '<option value="">-- Select District --</option>';
            return;
        }

        fetch("{% url 'load_districts' %}?region=" + encodeURIComponent(region))
            .then(res => res.json())
            .then(data => {
                districtSelect.innerHTML = '<option value="">-- Select District --</option>';
                data.districts.forEach(d => {
                    const option = document.createElement("option");
                    option.value = d;
                    option.textContent = d;
                    districtSelect.appendChild(option);
                });
            })
            .catch(err => console.error(err));
    });
});
</script>
```

---

## ✅ Features

* List all **Tanzania regions**
* List **districts by region**
* Works with **Django forms**, **vanilla JS**, or plain Python
* Fully **offline-ready**
* Can be extended for **wards** or other administrative levels

---

## 🔧 Advanced Usage

Preload all districts for **no-AJAX forms**:

```python
from tanzania_locations import get_regions, get_districts

locations = {region: get_districts(region) for region in get_regions()}
```

Now your JS can populate **district dropdowns instantly** without any server requests.

---

## 📜 License

MIT License – free to use, modify, and distribute.

---

## 💡 Example Output

```python
from tanzania_locations import get_regions, get_districts

for region in get_regions():
    print(region, get_districts(region))
```

This prints all regions and their districts, perfect for **forms, scripts, or data analysis**.

---

## 🤝 Contributing

Found a bug or have a feature request? Please keep in touch to: `mtavangucornel@gmail.com`

## 📞 Support

For help or questions:
- Check the documentation above
- Ensure you're using the latest version of the package

---

*Happy coding with Tanzania Locations! 🇹🇿*
