Django Nigerian States is a comprehensive third-party Django application that provides a robust and efficient way to manage and interact with geopolitical data related to Nigeria. This application is designed to seamlessly integrate with your Django projects, providing pre-defined Django fields for all states, their capitals, local government areas, and geopolitical zones in Nigeria.
- Python 3.10
- Django 5.0.1
-
Install Nigerian States using pip:
pip install django_nigerian_states
-
Add
'nigerian_states'toINSTALLED_APPSin your Django project's settings. -
Migrate your database:
python manage.py makemigrations python manage.py migrate
-
Load Fixtures:
python manage.py loaddata fixtures
You can integrate Nigerian States into your Django forms seamlessly. Below is an example:
from django import forms
from nigerian_states.fields import StateFormField, LocalGovernmentField
class AboutForm(forms.ModelForm):
zone = GeoPoliticalZoneField(
label="Zone",
help_text="Select a zone from the dropdown",
widget=forms.Select(attrs={"class": "form-select"}),
)
state = StateField(
label="Name of States",
help_text="Select a state from the dropdown",
widget=forms.Select(
attrs={"class": "form-select", "required": "required"}
),
)
lga = LocalGovernmentField(
label="Local Governments",
help_text="Select a LGA from the dropdown",
widget=forms.Select(
attrs={"class": "form-select", "required": "required"}
),
)You can configure Nigerian States by modifying your Django project settings.py:
DEFAULT_GEO_POLITICAL_ZONES = ["North Central", "North West"]Setting DEFAULT_GEO_POLITICAL_ZONES restricts the choices for (GeoPoliticalZoneField, StateField, or LocalGovernmentField) to the specified zones.
You can also customize fields further by utilizing additional keyword arguments like empty_label and zones:
from django import forms
from nigerian_states.fields import StateFormField, LocalGovernmentField
from nigerian_states.enums import PoliticalZones
zone = GeoPoliticalZoneField(
label="Zone",
empty_label="Select a GeoPolitical Zone", # the first option in the dropdown
zones=[PoliticalZones.SOUTH_EAST, PoliticalZones.SOUTH_EAST], # limits the field to specified political zones, overriding DEFAULT_GEO_POLITICAL_ZONES
)Note: In the above, by passing the zones kwargs in the field, It would override the DEFAULT_GEO_POLITICAL_ZONES set in the settings.py
To use the template tags, you need put {% load state_tags %} at the top of your django template.
The following template tags are available for use in your Django templates:
{% get_states_in_zone ZONE_NAME %}: Retrieves the list of states in a geopolitical zone.{% get_capital STATE_NAME %}: Returns the capital of the state provided{% get_lgas_in_state STATE_NAME %}: Retrieves the list of names of Local Government in the state.{% is_state_in_zone ZONE_NAME STATE_NAME %}: Returns a boolean True if the state is from the GeoPolitical Zone.{% is_lga_in_state STATE_NAME LGA_NAME %}: Returns a boolean True if the lga is from the state. else False{% default_zone %}: Returns the default zone set in the settings.DEFAULT_GEO_POLITICAL_ZONES if set or empty list{% get_zone STATE_NAME %}:Returns the name of the Zone which the state belongs to{% get_zone_info STATE_NAME %}: Returns a dict of information about the state.
To run the tests locally, follow these steps:
- Install dependencies:
pip install -r requirements.txt- Run test;
python manage.py run_testsContributions are welcomed and appreciated! Follow these steps to contribute:
- Fork the repository.
- Create a new branch for your feature or bug fix.
- Make changes, ensuring to write tests to confirm your changes did not break anything.
- Push the changes to your fork.
- Submit a pull request.
This project is licensed under the MIT License - see the LICENSE file for details.