1. Simon Meers
  2. django-countries

Commits

Chris Beaven  committed 2cf6af0

Push to 1.0, add some docstrings and a README (and change the FieldCountry class to just Country for simplicity).

  • Participants
  • Parent commits c68b7e2
  • Branches default

Comments (0)

Files changed (5)

File MANIFEST.in

View file
+recursive-include django_countries/media/flags *.gif

File README

View file
+================
+django-countries
+================
+
+A Django application which provides country choices for use with forms, and
+a country field for models.
+
+To use the flags, you will want to copy the flags directory of
+``django_countries/media`` to your static files directory, or use the
+`django-staticfiles`_ application.
+
+.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
+
+
+CountryField
+============
+
+A country field for Django models that provides all ISO 3166-1 countries as
+choices.
+
+``CountryField`` is based on Django's ``CharField``, providing choices
+corresponding to the official ISO 3166-1 list of countries (with a default
+``max_length`` of 2).
+
+Consider the following model using a ``CountryField``::
+
+    from django.db import models
+    from django_countries import CountryField
+
+    class Person(models.Model):
+        name = models.CharField(max_length=100)
+        country = CountryField()
+
+Any ``Person`` instance will have a ``country`` attribute that you can use to
+get details of the person's country:
+
+>>> person = Person(name='Chris', country='NZ')
+>>> person.country
+<person
+>>> person.country.name
+u'New Zealand'
+>>> person.country.flag
+u'/static/flags/nz.gif'
+
+This object (``person.country`` in the example) is a ``Country`` instance,
+which is described below.
+
+The ``Country`` object
+----------------------
+
+An object used to represent a country, instanciated with a two character
+country code.
+
+It can be compared to other objects as if it was a string containing the
+country code, and it's ``__unicode__`` method returns the country code.  
+
+name
+  Contains the full country name.
+
+flag
+  Contains a URL to the flag. ``'flags/[lowercasecountrycode].gif'`` is
+  appended to the ``STATIC_URL`` setting, or if that isn't set, the
+  ``MEDIA_URL`` setting.
+
+
+Country Choices
+===============
+
+The ``django_countries.countries`` module contains some constants which can be
+used to generate choices lists for a Django ``Select`` form field.
+
+``COUNTRIES``
+  A tuple of two part tuples, each consisting of a country code and the
+  corresponding nicely titled (and translatable) country name.
+
+``COUNTRIES_PLUS``
+  A tuple, similar to ``COUNTRIES``, but also includes duplicates for countries
+  that contain a comma (i.e. the non-comma'd version).
+
+``OFFICIAL_COUNTRIES``
+  A dictionary where each key is a country code and each value is the
+  corresponding official capitalised ISO 3166-1 English country name.

File django_countries/bin/regenerate.py

View file
 #!/usr/bin/env python
+"""
+This module can be used to regenerate the ``django_countries.countries``
+module.
+
+To regenerate that module to contain the latest list of ISO 3166-1 countries,
+either call this module directly from the command line
+(``python regenenerate.py``), or call the ``regenerate`` method.
+
+"""
+
 import os
 import re
 import string

File django_countries/fields.py

View file
 from django_countries import settings
 
 
-class FieldCountry(object):
+class Country(object):
     def __init__(self, code):
         self.code = code
     
 
 class CountryDescriptor(object):
     """
-    A descriptor for country fields on a model instance. Returns a FieldCountry
-    when accessed so you can do stuff like::
+    A descriptor for country fields on a model instance. Returns a Country when
+    accessed so you can do stuff like::
 
         >>> instance.country.name
         u'New Zealand'
             raise AttributeError(
                 "The '%s' attribute can only be accessed from %s instances."
                 % (self.field.name, owner.__name__))
-        return FieldCountry(code=instance.__dict__[self.field.name])
+        return Country(code=instance.__dict__[self.field.name])
 
     def __set__(self, instance, value):
         instance.__dict__[self.field.name] = force_unicode(value)
 
     def get_prep_value(self, value):
         "Returns field's value prepared for saving into a database."
-        # Convert the FieldCountry to unicode for database insertion.
+        # Convert the Country to unicode for database insertion.
         if value is None:
             return None
         return unicode(value)

File setup.py

View file
 #!/usr/bin/env python
+import os
 from setuptools import setup, find_packages
 
+
+def long_description():
+    """
+    Build the long description from a README file located in the same directory
+    as this module.
+
+    """
+    base_path = os.path.dirname(os.path.realpath(__file__))
+    readme = open(os.path.join(base_path, 'README'))
+    try:
+        return readme.read()
+    finally:
+        readme.close()
+
+
 setup(name='django-countries',
-      version='1.0a3',
+      version='1.0',
       description='Provides a country field for Django models.',
+      long_description=long_description(),
       author='Chris Beaven',
       author_email='smileychris@gmail.com',
       url='http://bitbucket.org/smileychris/django-countries/',
       # titlecase PYPI is broken, copied the module directly for now (in /bin)
 #      requires=['titlecase'],
       classifiers=[
-          'Development Status :: 3 - Alpha',
+          'Development Status :: 4 - Beta',
           'Environment :: Web Environment',
           'Intended Audience :: Developers',
           'License :: OSI Approved :: MIT License',