Metadata-Version: 2.1
Name: django-ph-geography
Version: 1.0.0
Summary: Philippine Geography models for Django
Home-page: https://github.com/josemarimanio/django-ph-geography/
Author: Jose Mari Manio
Author-email: josemari.manio@tutamail.com
License: MIT
Project-URL: Source Code, https://github.com/josemarimanio/django-ph-geography/
Description: .. image:: https://img.shields.io/pypi/v/django-ph-geography
            :alt: PyPi
            :target: https://pypi.org/project/django-ph-geography
        
        .. image:: https://img.shields.io/pypi/pyversions/django-ph-geography
            :alt: PyPI - Python Version
            :target: https://pypi.org/project/django-ph-geography
        
        .. image:: https://img.shields.io/pypi/djversions/django-ph-geography
            :alt: PyPI - Django Version
            :target: https://pypi.org/project/django-ph-geography
        
        .. image:: https://travis-ci.com/josemarimanio/django-ph-geography.svg?branch=main
            :alt: Travis CI
            :target: https://travis-ci.com/josemarimanio/django-ph-geography
        
        .. image:: https://www.codefactor.io/repository/github/josemarimanio/django-ph-geography/badge
            :alt: CodeFactor Grade
            :target: https://www.codefactor.io/repository/github/josemarimanio/django-ph-geography
        
        .. image:: https://img.shields.io/codecov/c/github/josemarimanio/django-ph-geography
            :alt: Codecov
            :target: https://codecov.io/gh/josemarimanio/django-ph-geography
        
        .. image:: https://img.shields.io/github/license/josemarimanio/django-ph-geography
            :alt: License - MIT
            :target: https://github.com/josemarimanio/django-ph-geography/blob/master/LICENSE
        
        
        Philippine Geography models for Django
        ======================================
        
        **django-ph-geography** provides models for integrating regions, provinces, municipalities, and barangays in the Philippines.
        
        Data retrieved from the Philippine Standard Geographic Code (PSGC) published by Philippine Statistics Authority (PSA) on March 31, 2020 (https://psa.gov.ph/classification/psgc/downloads/PSGC%20Publication%20March2020.xlsx).
        
        
        Table of Contents
        -----------------
        - `Installation <#installation>`_
        - `Models <#models>`_
        - `Monkey Patching <#monkey-patching>`_
        
        
        Installation
        ------------
        
        Installing using `pip <https://pip.pypa.io/en/stable/quickstart/>`_:
        
        .. code-block:: console
        
            pip install django-ph-geography
        
        
        Add ``ph_geography`` to ``INSTALLED_APPS``:
        
        .. code-block:: python
        
            INSTALLED_APPS = [
                ...
                'ph_geography',
            ]
        
        
        Migrate app models to database:
        
        .. code-block:: console
        
            python manage.py migrate ph_geography
        
        
        Load initial data:
        
        .. code-block:: console
        
            python manage.py phgeofixtures
        
        
        Models
        ------
        
        ph_geography.models.Region
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Model for regions. Available fields are:
        
        - ``code`` (``CharField<max_length=10, unique=True, null=False>``): Unique geographical code for region.
        - ``name`` (``CharField<max_length=100, null=False)>``): Geographical name for region.
        - ``population`` (``PositiveIntegerField<null=True>``): Population count based on 2015 POPCEN. Null value means no data is available.
        - ``island_group`` (``CharField<max_length=1, choices=ISLAND_GROUP_CHOICES, null=False>``): Island group where the region is located. Possible values are based on items in model property ``ISLAND_GROUP_CHOICES``:
        
          + ``ISLAND_GROUP_LUZON`` (``'L'``) - Luzon
          + ``ISLAND_GROUP_VISAYAS`` (``'V'``) - Visayas
          + ``ISLAND_GROUP_MINDANAO`` (``'M'``) - Mindanao
        - ``is_active`` (``BooleanField<null=False, default=True>``): Toggle if region is active (``True``) or not (``False``).
        
        
        ph_geography.models.Province
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Model for provinces. Available fields are:
        
        - ``code`` (``CharField<max_length=10, unique=True, null=False>``): Unique geographical code for region.
        - ``name`` (``CharField<max_length=100, null=False)>``): Geographical name for region.
        - ``population`` (``PositiveIntegerField<null=True>``): Population count based on 2015 POPCEN. Null value means no data is available.
        - ``region`` (``ForeignKey<Region, related_name='provinces', related_query_name='province', null=False, on_delete=models.CASCADE>``): Region where province is located.
        - ``income_class`` (``CharField<max_length=1, choices=INCOME_CLASS_CHOICES, null=False, blank=True>``): Income classification. Blank value means no data is available. Possible values are based on items in model property ``INCOME_CLASS_CHOICES``:
        
          + ``INCOME_CLASS_1`` (``'1'``) - 1st
          + ``INCOME_CLASS_2`` (``'2'``) - 2nd
          + ``INCOME_CLASS_3`` (``'3'``) - 3rd
          + ``INCOME_CLASS_4`` (``'4'``) - 4th
          + ``INCOME_CLASS_5`` (``'5'``) - 5th
          + ``INCOME_CLASS_6`` (``'6'``) - 6th
          + ``INCOME_CLASS_SPECIAL`` (``'S'``) - Special
        - ``is_active`` (``BooleanField<null=False, default=True>``): Toggle if province is active (``True``) or not (``False``).
        
        
        Available properties:
        
        - ``island_group``: Reference to ``Region`` field ``island_group``.
        
        
        ph_geography.models.Municipality
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Model for municipalities and cities. Available fields are:
        
        - ``code`` (``CharField<max_length=10, unique=True, null=False>``): Unique geographical code for region.
        - ``name`` (``CharField<max_length=100, null=False)>``): Geographical name for region.
        - ``population`` (``PositiveIntegerField<null=True>``): Population count based on 2015 POPCEN. Null value means no data is available.
        - ``province`` (``ForeignKey<Province, related_name='municipalities', related_query_name='municipality', null=False, on_delete=models.CASCADE>``): Province where municipality is located.
        - ``income_class`` (``CharField<max_length=1, choices=INCOME_CLASS_CHOICES, null=False, blank=True>``): Income classification. Blank value means no data is available. Possible values are based on items in model property ``INCOME_CLASS_CHOICES``:
        
          + ``INCOME_CLASS_1`` (``'1'``) - 1st
          + ``INCOME_CLASS_2`` (``'2'``) - 2nd
          + ``INCOME_CLASS_3`` (``'3'``) - 3rd
          + ``INCOME_CLASS_4`` (``'4'``) - 4th
          + ``INCOME_CLASS_5`` (``'5'``) - 5th
          + ``INCOME_CLASS_6`` (``'6'``) - 6th
          + ``INCOME_CLASS_SPECIAL`` (``'S'``) - Special
        - ``is_city`` (``BooleanField<null=False>``): Toggle to define whether the municipality is a city (``True``) or not (``False``).
        - ``is_capital`` (``BooleanField<null=False>``): Toggle to define whether the municipality is a capital (``True``) or not (``False``).
        - ``city_class`` (``CharField<max_length=1, choices=CITY_CLASS_CHOICES, null=False, blank=True>``): City legal classification. Blank value means no data is available. Possible values are based on items in model property ``CITY_CLASS_CHOICES``:
        
          + ``CITY_CLASS_COMPONENT_CITY`` (``'C'``) - CC
          + ``CITY_CLASS_INDEPENDENT_COMPONENT_CITY`` (``'I'``) - ICC
          + ``CITY_CLASS_HIGHLY_URBANIZED_CITY`` (``'H'``) - HUC
        - ``is_active`` (``BooleanField<null=False, default=True>``): Toggle if municipality is active (``True``) or not (``False``).
        
        
        Available properties:
        
        - ``island_group``: Reference to ``Region`` field ``island_group``.
        - ``region``: Reference to ``province`` field ``region``.
        
        
        ph_geography.models.Barangay
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Model for barangays. Available fields are:
        
        - ``code`` (``CharField<max_length=10, unique=True, null=False>``): Unique geographical code for region.
        - ``name`` (``CharField<max_length=100, null=False)>``): Geographical name for region.
        - ``population`` (``PositiveIntegerField<null=True>``): Population count based on 2015 POPCEN. Null value means no data is available.
        - ``municipality`` (``ForeignKey<Municipality>, related_name='barangays', related_query_name='barangay', null=False, on_delete=models.CASCADE>``): Municipality where barangay is located.
        - ``is_urban`` (``NullBooleanField<null=False>``): Toggle to define whether the barangay is urban (``True``) or rural (``False``). Null value means no data is available.
        - ``is_active`` (``BooleanField<null=False, default=True>``): Toggle if barangay is active (``True``) or not (``False``).
        
        
        Available properties:
        
        - ``island_group``: Reference to ``Region`` field ``island_group``.
        - ``province``: Reference to ``municipality`` field ``province``.
        - ``region``: Reference to property ``province`` field ``region``.
        
        
        
        Monkey Patching
        ---------------
        
        After migrating the models and loading the initial data through fixtures, you can monkey patch (*if you're into it*) **django-ph-geography** models using the provided methods to suit your needs:
        
        
        Adding new fields
        ^^^^^^^^^^^^^^^^^
        
        You can use the custom method ``add_field`` provided by abstract model class ``ph_geography.models.PhilippineGeography`` to add fields to the models provided.
        Using the said method to the abstract model will apply the action to all subclasses.
        
        Example:
        
        .. code-block:: python
        
            from django.db import models
        
            from ph_geography.models import PhilippineGeography
            from ph_geography.models import Region
        
        
            # Add field to Region, Province, Municipality, Barangay, and any subclass models of PhilippineGeography
            PhilippineGeography.add_field('all_models', models.BooleanField(null=True))
        
            # Add field 'single_model' to Region
            Region.add_field('single_model', models.BooleanField(null=True))
        
        
        Removing existing fields
        ^^^^^^^^^^^^^^^^^^^^^^^^
        
        You can use the custom method ``remove_field`` provided by abstract model class ``ph_geography.models.PhilippineGeography`` to remove fields to the models provided.
        Using the same method to the abstract model will apply the action to all subclasses.
        
        Example:
        
        .. code-block:: python
        
            from ph_geography.models import PhilippineGeography
            from ph_geography.models import Municipality
            from ph_geography.models import Region
        
        
            # Remove field to Region, Province, Municipality, Barangay, and any subclass models of PhilippineGeography
            PhilippineGeography.remove_field('population')
        
            # Remove field 'island_group' from Region
            Region.remove_field('island_group')
        
            # Multiple fields to remove are supported
            Municipality.remove_field('is_city', 'is_capital')
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django :: 1.11
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.0
Classifier: Framework :: Django :: 3.1
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.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.4
Description-Content-Type: text/x-rst
Provides-Extra: test
