# Django-GlobalPlaces
Plug and play configurations and data for countries, states and cities from all over the globe.
## Requirements
- Django >= 3.8 *
- Python >= 3.8 *
- Django Rest Framework >= 3.13 *
- This requirement is only necessary if you are using the provided REST endpoints.
- django-filter >= 23.0 *
- This requirement is only necessary if you are using the provided REST endpoints.
- pytest-django >= 4.0 *
- This requirement is only necessary if you are running the tests and use Django Rest Framework.
- factory_boy >= 3.0 *
- This requirement is only necessary if you are running the tests and use Django Rest Framework.
(*) Last tested versions
- Django==5.1.1
- Python==3.10.9
- djangorestframework==3.15.2
- django-filter==24.3
- pytest-django==4.9.0
- factory_boy==3.3.1
## Quick Setup
Install package
pip install django-global-places
Add `django_global_places` app to INSTALLED_APPS in your django settings.py:
```python
INSTALLED_APPS = (
...,
"django.contrib.staticfiles",
'django_global_places'
'rest_framework', # required only if using the provided REST endpoints
...,
)
```
(Optional) Include viewset routes
```python
from django_global_places.urls import router as django_global_places_router
your_router.registry.extend(django_global_places_router.registry)
```
### Explanation
This library handles the configuration and creation of `Countries`, `States`, and `Cities`.
After installation, you need to specify three parameters in your `settings.py` file:
- `INCLUDE_LOCATION`: Enables the creation of the models.
- `LOCATION_SCOPE`: Determines the scope of models required ('country', 'state', or 'city').
- `INCLUDE_EXPANDED_COUNTRY`: Incorporates additional fields into the Country model.
And you have this 3 optional extra parameters:
- `COUNTRY_MODEL`: Allows you to integrate the library with a custom country model in case you need extra fields.
- `STATE_MODEL`: Allows you to integrate the library with a custom state model in case you need extra fields.
- `CITY_MODEL`: Allows you to integrate the library with a custom city model in case you need extra fields.
Example:
```
GLOBAL_PLACES = {
"INCLUDE_LOCATION": True,
"LOCATION_SCOPE": "state",
"INCLUDE_EXPANDED_COUNTRY": False,
"COUNTRY_MODEL": "django_global_places.Country",
"STATE_MODEL": "django_global_places.State",
"CITY_MODEL": "django_global_places.City",
}
```
Once these variables are configured, your next steps are to run django `migrate` command.
To **populate** the newly created models, you should execute a Django command. This command will create all the necessary objects and update them if they already exist.
```
python manage.py populate_global_places
```
### Rest endpoints
Three viewsets are included, one for each model: `Country`, `State`, and `City`. Each viewset features:
A list view displaying a summary of the objects.
A detail view presenting comprehensive information about each object.
- CountryViewSet:
- url: global-places/countries
- search fields: `name` and `iso3`
- ordering fields: `id`, `name` and `iso3`
- StateViewSet:
- url: global-places/states
- search fields: `name` and `state_code`
- ordering fields: `id`, `name` and `state_code`
- filtering fields: `country`
- CityViewSet:
- url: global-places/cities
- search fields: `name`
- ordering fields: `id` and `name`
- filtering fields: `state`, `state__country`
Full examples [here](https://www.postman.com/restless-zodiac-765340/workspace/django-globalplaces/collection/18007906-46245b57-0675-4bfb-ae41-c71ee6f6f6f5?action=share&creator=18007906) in Postman collection.
### Tests
To run the tests, you need to have the `pytest-django` and `factory_boy` packages installed. You can run the tests with the following command:
```
pytest
```
### Using custom models
The library allows the use of customized models in case additional fields need to be added to the existing models.
It is important that the custom models inherit from the library's abstract classes. For this, there are methods in the utils that return the corresponding abstract model for each one.
Once created, they must be specified in the library configuration as indicated above. This will allow the database population command to use those models instead of the default ones.
### Acknowledgements
Special thanks to the [Countries States Cities Database](https://github.com/dr5hn/countries-states-cities-database) for providing the JSON files used for populating the data.
## Contributing
- [Luca Cittá Giordano](https://www.linkedin.com/in/lucacittagiordano/)
- [Matias Girardi](https://www.linkedin.com/in/matiasgirardi)
- [Juan Ignacio Borrelli](https://www.linkedin.com/in/juan-ignacio-borrelli/)
Maintained and developed by [Linkchar Software Development](https://linkchar.com/).
Raw data
{
"_id": null,
"home_page": "https://github.com/lucacitta/Django-GlobalPlaces",
"name": "django-global-places",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "django global places",
"author": "lucacitta",
"author_email": "lucacitta.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e5/1b/87014e49a4e4943e0a1fe9294b7c38b73af1037eafcfce3de455fd6fcd41/django_global_places-0.9.0.tar.gz",
"platform": null,
"description": "# Django-GlobalPlaces\r\nPlug and play configurations and data for countries, states and cities from all over the globe.\r\n\r\n## Requirements\r\n- Django >= 3.8 *\r\n- Python >= 3.8 *\r\n- Django Rest Framework >= 3.13 *\r\n\t- This requirement is only necessary if you are using the provided REST endpoints.\r\n- django-filter >= 23.0 *\r\n\t- This requirement is only necessary if you are using the provided REST endpoints.\r\n- pytest-django >= 4.0 *\r\n\t- This requirement is only necessary if you are running the tests and use Django Rest Framework.\r\n- factory_boy >= 3.0 *\r\n\t- This requirement is only necessary if you are running the tests and use Django Rest Framework.\r\n\r\n(*) Last tested versions\r\n\t- Django==5.1.1\r\n\t- Python==3.10.9\r\n\t- djangorestframework==3.15.2\r\n\t- django-filter==24.3\r\n\t- pytest-django==4.9.0\r\n\t- factory_boy==3.3.1\r\n\r\n\r\n## Quick Setup\r\n\r\nInstall package\r\n\r\n pip install django-global-places\r\nAdd `django_global_places` app to INSTALLED_APPS in your django settings.py:\r\n\r\n```python\r\nINSTALLED_APPS = (\r\n ...,\r\n \"django.contrib.staticfiles\",\r\n 'django_global_places'\r\n 'rest_framework', # required only if using the provided REST endpoints\r\n ...,\r\n)\r\n```\r\n\r\n(Optional) Include viewset routes\r\n\r\n```python\r\nfrom django_global_places.urls import router as django_global_places_router\r\nyour_router.registry.extend(django_global_places_router.registry)\r\n```\r\n\r\n\r\n### Explanation\r\n\r\nThis library handles the configuration and creation of `Countries`, `States`, and `Cities`.\r\n\r\nAfter installation, you need to specify three parameters in your `settings.py` file:\r\n\r\n- `INCLUDE_LOCATION`: Enables the creation of the models.\r\n- `LOCATION_SCOPE`: Determines the scope of models required ('country', 'state', or 'city').\r\n- `INCLUDE_EXPANDED_COUNTRY`: Incorporates additional fields into the Country model.\r\n\r\nAnd you have this 3 optional extra parameters:\r\n- `COUNTRY_MODEL`: Allows you to integrate the library with a custom country model in case you need extra fields.\r\n- `STATE_MODEL`: Allows you to integrate the library with a custom state model in case you need extra fields.\r\n- `CITY_MODEL`: Allows you to integrate the library with a custom city model in case you need extra fields.\r\n\r\nExample:\r\n```\r\nGLOBAL_PLACES = {\r\n\t\"INCLUDE_LOCATION\": True,\r\n\t\"LOCATION_SCOPE\": \"state\",\r\n\t\"INCLUDE_EXPANDED_COUNTRY\": False,\r\n\t\"COUNTRY_MODEL\": \"django_global_places.Country\",\r\n\t\"STATE_MODEL\": \"django_global_places.State\",\r\n\t\"CITY_MODEL\": \"django_global_places.City\",\r\n}\r\n```\r\n\r\nOnce these variables are configured, your next steps are to run django `migrate` command.\r\n\r\nTo **populate** the newly created models, you should execute a Django command. This command will create all the necessary objects and update them if they already exist.\r\n\r\n```\r\npython manage.py populate_global_places\r\n```\r\n\r\n### Rest endpoints\r\n\r\nThree viewsets are included, one for each model: `Country`, `State`, and `City`. Each viewset features:\r\n\r\nA list view displaying a summary of the objects.\r\nA detail view presenting comprehensive information about each object.\r\n\r\n- CountryViewSet:\r\n\t- url: global-places/countries\r\n\t- search fields: `name` and `iso3`\r\n\t- ordering fields: `id`, `name` and `iso3`\r\n\r\n- StateViewSet:\r\n\t- url: global-places/states\r\n\t- search fields: `name` and `state_code`\r\n\t- ordering fields: `id`, `name` and `state_code`\r\n\t- filtering fields: `country`\r\n\r\n- CityViewSet:\r\n\t- url: global-places/cities\r\n\t- search fields: `name`\r\n\t- ordering fields: `id` and `name`\r\n\t- filtering fields: `state`, `state__country`\r\n\r\nFull examples [here](https://www.postman.com/restless-zodiac-765340/workspace/django-globalplaces/collection/18007906-46245b57-0675-4bfb-ae41-c71ee6f6f6f5?action=share&creator=18007906) in Postman collection.\r\n\r\n### Tests\r\n\r\nTo run the tests, you need to have the `pytest-django` and `factory_boy` packages installed. You can run the tests with the following command:\r\n\r\n```\r\npytest\r\n```\r\n\r\n### Using custom models\r\n\r\nThe library allows the use of customized models in case additional fields need to be added to the existing models.\r\n\r\nIt is important that the custom models inherit from the library's abstract classes. For this, there are methods in the utils that return the corresponding abstract model for each one.\r\n\r\nOnce created, they must be specified in the library configuration as indicated above. This will allow the database population command to use those models instead of the default ones.\r\n\r\n### Acknowledgements\r\n\r\nSpecial thanks to the [Countries States Cities Database](https://github.com/dr5hn/countries-states-cities-database) for providing the JSON files used for populating the data.\r\n\r\n## Contributing\r\n\r\n- [Luca Citt\u00e1 Giordano](https://www.linkedin.com/in/lucacittagiordano/)\r\n\r\n- [Matias Girardi](https://www.linkedin.com/in/matiasgirardi)\r\n\r\n- [Juan Ignacio Borrelli](https://www.linkedin.com/in/juan-ignacio-borrelli/)\r\n\r\nMaintained and developed by [Linkchar Software Development](https://linkchar.com/).\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django Global Places is a simple Django app to provide a model for global places.",
"version": "0.9.0",
"project_urls": {
"Homepage": "https://github.com/lucacitta/Django-GlobalPlaces"
},
"split_keywords": [
"django",
"global",
"places"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5534a4d4533019bf497c671eb6ba2895dc5832922c550fcee8c4cb50c270c9f5",
"md5": "0d4cd6fe4e1b89d105037a353f484e40",
"sha256": "134bf3ff4bb184247527f213a11e74d2c4779d3293f336f9f6e6e1607cd6ca4e"
},
"downloads": -1,
"filename": "django_global_places-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0d4cd6fe4e1b89d105037a353f484e40",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17308,
"upload_time": "2024-10-21T19:11:56",
"upload_time_iso_8601": "2024-10-21T19:11:56.695713Z",
"url": "https://files.pythonhosted.org/packages/55/34/a4d4533019bf497c671eb6ba2895dc5832922c550fcee8c4cb50c270c9f5/django_global_places-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e51b87014e49a4e4943e0a1fe9294b7c38b73af1037eafcfce3de455fd6fcd41",
"md5": "3fb2b08cf16f9c1a9d5c7ada03aaeb5e",
"sha256": "8853d3b5346d0a6db81151b532b9d74bfc7821074f473ec767daac9a4c0c7bbf"
},
"downloads": -1,
"filename": "django_global_places-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "3fb2b08cf16f9c1a9d5c7ada03aaeb5e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13382,
"upload_time": "2024-10-21T19:11:58",
"upload_time_iso_8601": "2024-10-21T19:11:58.557103Z",
"url": "https://files.pythonhosted.org/packages/e5/1b/87014e49a4e4943e0a1fe9294b7c38b73af1037eafcfce3de455fd6fcd41/django_global_places-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-21 19:11:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lucacitta",
"github_project": "Django-GlobalPlaces",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-global-places"
}
JSON
