Package: nuclear-postaladdress
Nuclear Postal AddressDjango models for storing and retrieving postal addresses.OverviewPostal Address is a set of models and methods for working with postal addresses.RequirementsPython (3.5, 3.6, 3.7, 3.8)Django (3.0)Werecommendand only officially support the latest patch release of each Python and Django series.InstallationFor more detailed instructions,view the Readme for the example siteincluded with this package.pipinstallnuclear-postaladdressThen, addaddressto yourINSTALLED_APPSlist insettings.py:INSTALLED_APPS = [
    # ... 
    'nuclera_postaladdress',
    # ... 
]You can either store your Google API key in an environment variable asGOOGLE_API_KEYor you can
specify the key insettings.py. If you have an environment variable set it will override what you put in settings.py.
For more information, including enabling the Google Places API, refer tothe example site.GOOGLE_API_KEY = 'AIzaSyD--your-google-maps-key-SjQBE'The ModelThe rationale behind the model structure is centered on trying to make
it easy to enter addresses that may be poorly defined. The model field included
uses Google Maps API v3 (via the nicely donegeocomplete jquery plugin) to
determine a proper address where possible. However if this isn't possible the
raw address is used and the user is responsible for breaking the address down
into components.It's currently assumed any address is represent-able using four components:
country, state, locality and street address. In addition, country code, state
code and postal code may be stored, if they exist.There are four Django models used:Country
    name
    code

  State
    name
    code
    country -> Country

  Locality
    name
    postal_code
    state -> State

  Address
    raw
    street_number
    route
    locality -> LocalityAddress FieldTo simplify storage and access of addresses, a subclass ofForeignKeynamedAddressFieldhas been created. It provides an easy method for setting new
addresses.ON_DELETE behavior of Address FieldBy default, if you delete an Address that is related to another object,
Django'scascade behavioris used. This means the related object will also be deleted. You may also choose
to setnull=Truewhen defining an address field to have the address set
to Null instead of deleting the related object. For more information and an example,
see the readme for thenuclear-postaladdressexample_site.CreationIt can be created using the same optional arguments as a ForeignKey field.
For example:fromaddress.modelsimportAddressFieldclassMyModel(models.Model):address1=AddressField()address2=AddressField(related_name='+',blank=True,null=True)Setting ValuesValues can be set either by assigning an Address object:addr=Address(...)addr.save()obj.address=addrOr by supplying a dictionary of address components:obj.address={'street_number':'1','route':'Somewhere Ave',...}The structure of the address components is as follows:{'raw':'1 Somewhere Ave, Northcote, VIC 3070, AU','street_number':'1','route':'Somewhere Ave','locality':'Northcote','postal_code':'3070','state':'Victoria','state_code':'VIC','country':'Australia','country_code':'AU'}All except therawfield can be omitted. In addition, a raw address may
be set directly:obj.address='Out the back of 1 Somewhere Ave, Northcote, Australia'Getting ValuesWhen accessed, the address field simply returns an Address object. This way
all components may be accessed naturally through the object. For example::route=obj.address.routestate_name=obj.address.locality.state.nameFormsIncluded is a form field for simplifying address entry. A Google maps
auto-complete is performed in the browser and passed to the view. If
the lookup fails the raw entered value is used.TODO: Talk about this more.Partial ExampleThe model:fromaddress.modelsimportAddressFieldclassPerson(models.Model):address=AddressField(on_delete=models.CASCADE)The form:from address.forms import AddressField

class PersonForm(forms.Form):
  address = AddressField()The template:<head>{{ form.media }}<!-- needed for JS/GoogleMaps lookup --></head><body>{{ form }}</body>Running Nuclear Postaladresses TestsNuclear Postaladdress currently has partial form and model test coverage usingdjango.test.TestCase.To run the current tests:Clonenuclear-postaladdresslocally.Navigate to the example site, ./nuclear-postaladdress/example_siteCreate avirtual environmentand install the example site dependencies. For example:mkvirtualenv -p python3 nuclear-postaladdresses
pip install -r requirements.txtRun./manage.py testImportant note regarding US TerritoriesNuclear Postaladdresses does not currently support the parsing of US territories aka Protectorates such as Guam or Puerto Rico.Project Status NotesThis library was created byLuke Hodkinsonoriginally focused on Australian addresses.In 2015 Luke began working to abstract the project so it could handle a wider variety of international addresses.This became the currentdevbranch.  While good progress was made on this, the branch became stale and releases
continued under the current model architecture on master.The project is currently in open development, read more about the project statusin this issue.If you have questions, bug reports or suggestions please create a New Issue for the project.