Anonymous avatar Anonymous committed 5daa7ec

adding subdivision search method and updating documentation

Comments (0)

Files changed (2)

 
 Approximate country and language name matching for `pycountry`, making it an even better reference for messy data.
 
+## Important Note
+
+**Globetrotter-Provinces requires a [forked version](https://bitbucket.org/kuranes/pycountry) of pycountry that creates indexes on the 'name' field of a subdivision.**
+
 ## Motivation
 
 ```
     return self.indices[field][value]
 KeyError: 'Vietnam'
 >>>
+>>> pycountry.subdivisions.get(name='LasTunas')
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+  File "/Users/you/Library/Python/2.7/lib/python/site-packages/pycountry/db.py", line 87, in get
+    return self.indices[field][value]
+KeyError: 'LasTunas'
+>>> 
 ```
 
 'Nuff said.
 ## Installation
 
 ```
-pip install globetrotter
+pip install -e hg+http://bitbucket.org/kuranes/pycounty#egg=pycountry
 ```
 
 ## Usage
 
 ```
 >>> import globetrotter
-g>>> globetrotter.find_country('Vietnam')
+>>> globetrotter.find_country('Vietnam')
 <pycountry.db.Country object at 0x1038eed90>
 >>> globetrotter.find_country('Vietnam').name
 u'Viet Nam'
 u'Spanish; Castilian'
 ```
 
+Find a subdivision through the `find_subdivision()` method in a similar way. It returns a `Subdivision` object.
+
+```
+>>> import globetrotter
+>>> globetrotter.find_subdivision('LasTunas')
+<pycountry.db.Subdivision at 0xbb71a2c>
+>>> globetrotter.find_subdivision('LasTunas').name
+u'Las Tunas'
+```
         raise KeyError(name)
     return c
 
+def find_subdivision(name):
+    "Find a subdivision's information given an approximate name."
+    norm_name = _norm_subdivisions[_norm_string(name)]
+    c = pycountry.subdivisions.get(name=norm_name)
+    if not c:
+        raise KeyError(name)
+    return c
+
 def find_language(name):
     "Find a language's information given an approximate name."
     norm_query = _norm_string(name)
 _norm_countries = {_norm_string(c.name): c.name
         for c in pycountry.countries.objects}
 
+_norm_subdivisions = {_norm_string(c.name): c.name
+        for c in pycountry.subdivisions.objects}
+
 _norm_languages = {_norm_string(l.name): l.name
         for l in pycountry.languages.objects}
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.