Tweaks to Country model

* Added some docstrings because I kept having to look up details
  of the implementation
* Removed index on the alpha3 and numeric code because we never use
  those fields for lookups
* Turned the numeric field into a CharField as suggested

docs/source/releases/v0.8.rst

@@ -454,6 +454,7 @@ Migrations
 * Address:
 
     - ``0011`` - ``AbstractAddress.search_text`` turned into a ``TextField``.
+    - ``0012`` - ``AbstractCountry``: Removed two unused indexes & turns numeric code into ``CharField``
 
 * Catalogue:
 

oscar/apps/address/abstract_models.py

@@ -376,24 +376,30 @@ class AbstractAddress(models.Model):
 class AbstractCountry(models.Model):
     """
     International Organization for Standardization (ISO) 3166-1 Country list.
+
+    The field names are a bit awkward, but kept for backwards compatibility.
+    pycountry's syntax of alpha2, alpha3, name and official_name seems sane.
     """
-    iso_3166_1_a2 = models.CharField(_('ISO 3166-1 alpha-2'), max_length=2,
-                                     primary_key=True)
-    iso_3166_1_a3 = models.CharField(_('ISO 3166-1 alpha-3'), max_length=3,
-                                     blank=True, db_index=True)
-    # This should have been a CharField as it needs to be padded with zeros to
-    # be 3 digits.  Access via the numeric_code instead.
-    iso_3166_1_numeric = models.PositiveSmallIntegerField(
-        _('ISO 3166-1 numeric'), null=True, db_index=True)
-    name = models.CharField(_('Official name (CAPS)'), max_length=128)
+    iso_3166_1_a2 = models.CharField(
+        _('ISO 3166-1 alpha-2'), max_length=2, primary_key=True)
+    iso_3166_1_a3 = models.CharField(
+        _('ISO 3166-1 alpha-3'), max_length=3, blank=True)
+    iso_3166_1_numeric = models.CharField(
+        _('ISO 3166-1 numeric'), blank=True, max_length=3)
+
+    #: The commonly used name
+    #: e.g. 'United Kingdom'
     printable_name = models.CharField(_('Country name'), max_length=128)
+    #: The full official name of a country
+    #: e.g. 'United Kingdom of Great Britain and Northern Ireland'
+    name = models.CharField(_('Official name'), max_length=128)
 
     display_order = models.PositiveSmallIntegerField(
         _("Display order"), default=0, db_index=True,
         help_text=_('Higher the number, higher the country in the list.'))
 
-    is_shipping_country = models.BooleanField(_("Is Shipping Country"),
-                                              default=False, db_index=True)
+    is_shipping_country = models.BooleanField(
+        _("Is shipping country"), default=False, db_index=True)
 
     class Meta:
         abstract = True
@@ -407,13 +413,21 @@ class AbstractCountry(models.Model):
     @property
     def code(self):
         """
-        Shorthand for the ISO 3166 code
+        Shorthand for the ISO 3166 Alpha-2 code
         """
         return self.iso_3166_1_a2
 
     @property
     def numeric_code(self):
-        return u"%.03d" % self.iso_3166_1_numeric
+        """
+        Shorthand for the ISO 3166 numeric code.
+
+        iso_3166_1_numeric used to wrongly be a integer field, but has to be
+        padded with leading zeroes. It's since been converted to a char field,
+        but the database might still contain non-padded strings. That's why
+        the padding is kept.
+        """
+        return u"%.03d" % int(self.iso_3166_1_numeric)
 
 
 class AbstractShippingAddress(AbstractAddress):

oscar/apps/address/migrations/0012_auto__del_index_country_iso_3166_1_a3__chg_field_country_iso_3166_1_nu.py

@@ -0,0 +1,106 @@
+# -*- coding: utf-8 -*-
+from south.utils import datetime_utils as datetime
+from south.db import db
+from south.v2 import SchemaMigration
+from django.db import models
+
+from oscar.core.compat import AUTH_USER_MODEL, AUTH_USER_MODEL_NAME
+
+
+class Migration(SchemaMigration):
+
+    def forwards(self, orm):
+        # Removing index on 'Country', fields ['iso_3166_1_a3']
+        db.delete_index(u'address_country', ['iso_3166_1_a3'])
+
+
+        # Changing field 'Country.iso_3166_1_numeric'
+        db.alter_column(u'address_country', 'iso_3166_1_numeric', self.gf('django.db.models.fields.CharField')(default='', max_length=3))
+        # Removing index on 'Country', fields ['iso_3166_1_numeric']
+        db.delete_index(u'address_country', ['iso_3166_1_numeric'])
+
+
+    def backwards(self, orm):
+        # Adding index on 'Country', fields ['iso_3166_1_numeric']
+        db.create_index(u'address_country', ['iso_3166_1_numeric'])
+
+        # Adding index on 'Country', fields ['iso_3166_1_a3']
+        db.create_index(u'address_country', ['iso_3166_1_a3'])
+
+
+        # Changing field 'Country.iso_3166_1_numeric'
+        db.alter_column(u'address_country', 'iso_3166_1_numeric', self.gf('django.db.models.fields.PositiveSmallIntegerField')(null=True))
+
+    models = {
+        u'address.country': {
+            'Meta': {'ordering': "('-display_order', 'name')", 'object_name': 'Country'},
+            'display_order': ('django.db.models.fields.PositiveSmallIntegerField', [], {'default': '0', 'db_index': 'True'}),
+            'is_shipping_country': ('django.db.models.fields.BooleanField', [], {'default': 'False', 'db_index': 'True'}),
+            'iso_3166_1_a2': ('django.db.models.fields.CharField', [], {'max_length': '2', 'primary_key': 'True'}),
+            'iso_3166_1_a3': ('django.db.models.fields.CharField', [], {'max_length': '3', 'blank': 'True'}),
+            'iso_3166_1_numeric': ('django.db.models.fields.CharField', [], {'max_length': '3', 'blank': 'True'}),
+            'name': ('django.db.models.fields.CharField', [], {'max_length': '128'}),
+            'printable_name': ('django.db.models.fields.CharField', [], {'max_length': '128'})
+        },
+        u'address.useraddress': {
+            'Meta': {'ordering': "['-num_orders']", 'unique_together': "(('user', 'hash'),)", 'object_name': 'UserAddress'},
+            'country': ('django.db.models.fields.related.ForeignKey', [], {'to': u"orm['address.Country']"}),
+            'date_created': ('django.db.models.fields.DateTimeField', [], {'auto_now_add': 'True', 'blank': 'True'}),
+            'first_name': ('django.db.models.fields.CharField', [], {'max_length': '255', 'blank': 'True'}),
+            'hash': ('django.db.models.fields.CharField', [], {'max_length': '255', 'db_index': 'True'}),
+            u'id': ('django.db.models.fields.AutoField', [], {'primary_key': 'True'}),
+            'is_default_for_billing': ('django.db.models.fields.BooleanField', [], {'default': 'False'}),
+            'is_default_for_shipping': ('django.db.models.fields.BooleanField', [], {'default': 'False'}),
+            'last_name': ('django.db.models.fields.CharField', [], {'max_length': '255', 'blank': 'True'}),
+            'line1': ('django.db.models.fields.CharField', [], {'max_length': '255'}),
+            'line2': ('django.db.models.fields.CharField', [], {'max_length': '255', 'blank': 'True'}),
+            'line3': ('django.db.models.fields.CharField', [], {'max_length': '255', 'blank': 'True'}),
+            'line4': ('django.db.models.fields.CharField', [], {'max_length': '255', 'blank': 'True'}),
+            'notes': ('django.db.models.fields.TextField', [], {'blank': 'True'}),
+            'num_orders': ('django.db.models.fields.PositiveIntegerField', [], {'default': '0'}),
+            'phone_number': ('oscar.models.fields.PhoneNumberField', [], {'max_length': '128', 'blank': 'True'}),
+            'postcode': ('oscar.models.fields.UppercaseCharField', [], {'max_length': '64', 'blank': 'True'}),
+            'search_text': ('django.db.models.fields.TextField', [], {}),
+            'state': ('django.db.models.fields.CharField', [], {'max_length': '255', 'blank': 'True'}),
+            'title': ('django.db.models.fields.CharField', [], {'max_length': '64', 'blank': 'True'}),
+            'user': ('django.db.models.fields.related.ForeignKey', [], {'related_name': "'addresses'", 'to': u"orm['{0}']".format(AUTH_USER_MODEL)})
+        },
+        u'auth.group': {
+            'Meta': {'object_name': 'Group'},
+            u'id': ('django.db.models.fields.AutoField', [], {'primary_key': 'True'}),
+            'name': ('django.db.models.fields.CharField', [], {'unique': 'True', 'max_length': '80'}),
+            'permissions': ('django.db.models.fields.related.ManyToManyField', [], {'to': u"orm['auth.Permission']", 'symmetrical': 'False', 'blank': 'True'})
+        },
+        u'auth.permission': {
+            'Meta': {'ordering': "(u'content_type__app_label', u'content_type__model', u'codename')", 'unique_together': "((u'content_type', u'codename'),)", 'object_name': 'Permission'},
+            'codename': ('django.db.models.fields.CharField', [], {'max_length': '100'}),
+            'content_type': ('django.db.models.fields.related.ForeignKey', [], {'to': u"orm['contenttypes.ContentType']"}),
+            u'id': ('django.db.models.fields.AutoField', [], {'primary_key': 'True'}),
+            'name': ('django.db.models.fields.CharField', [], {'max_length': '50'})
+        },
+        AUTH_USER_MODEL: {
+            'Meta': {'object_name': AUTH_USER_MODEL_NAME},
+            'date_joined': ('django.db.models.fields.DateTimeField', [], {'default': 'datetime.datetime.now'}),
+            'email': ('django.db.models.fields.EmailField', [], {'max_length': '75', 'blank': 'True'}),
+            'first_name': ('django.db.models.fields.CharField', [], {'max_length': '30', 'blank': 'True'}),
+            'groups': ('django.db.models.fields.related.ManyToManyField', [], {'symmetrical': 'False', 'related_name': "u'user_set'", 'blank': 'True', 'to': u"orm['auth.Group']"}),
+            u'id': ('django.db.models.fields.AutoField', [], {'primary_key': 'True'}),
+            'is_active': ('django.db.models.fields.BooleanField', [], {'default': 'True'}),
+            'is_staff': ('django.db.models.fields.BooleanField', [], {'default': 'False'}),
+            'is_superuser': ('django.db.models.fields.BooleanField', [], {'default': 'False'}),
+            'last_login': ('django.db.models.fields.DateTimeField', [], {'default': 'datetime.datetime.now'}),
+            'last_name': ('django.db.models.fields.CharField', [], {'max_length': '30', 'blank': 'True'}),
+            'password': ('django.db.models.fields.CharField', [], {'max_length': '128'}),
+            'user_permissions': ('django.db.models.fields.related.ManyToManyField', [], {'symmetrical': 'False', 'related_name': "u'user_set'", 'blank': 'True', 'to': u"orm['auth.Permission']"}),
+            'username': ('django.db.models.fields.CharField', [], {'unique': 'True', 'max_length': '30'})
+        },
+        u'contenttypes.contenttype': {
+            'Meta': {'ordering': "('name',)", 'unique_together': "(('app_label', 'model'),)", 'object_name': 'ContentType', 'db_table': "'django_content_type'"},
+            'app_label': ('django.db.models.fields.CharField', [], {'max_length': '100'}),
+            u'id': ('django.db.models.fields.AutoField', [], {'primary_key': 'True'}),
+            'model': ('django.db.models.fields.CharField', [], {'max_length': '100'}),
+            'name': ('django.db.models.fields.CharField', [], {'max_length': '100'})
+        }
+    }
+
+    complete_apps = ['address']