Implement and document Person Version Read

CHANGELOG.rst

@@ -6,6 +6,7 @@
 ---
 
 * Supports Authorities requests (place, name, date, and culture)
+* Supports Person Version Read
 * Properly sends session ID on first request without needing to call session()
 * Search and Match return a single object instead of a one-item list
 * Supports pickling using any protocol (0-2)

README.rst

@@ -106,6 +106,12 @@ pass additional parameters to the API, simply pass them as named arguments::
 
   print fs.person(['ABCD-123', 'EFGH-456'], events='all', children='all')
 
+Print the latest version of a list of persons (this request is more lightweight
+than a full person request, so it supports more IDs at once)::
+
+  for person in fs.version(['ABCD-123', 'EFGH-456']):
+      print person['id'], person['version']
+
 Print current user's pedigree::
 
   print fs.pedigree()

ROADMAP.rst

@@ -17,6 +17,7 @@
 ---
 
 - Authorities Read
+- Person Version Read
 - Unit tests
 - Convenience methods to access FamilySearch's data model
 
@@ -26,7 +27,6 @@ Future
 
 - Use persistent HTTP connections instead of a new connection for each request
 - Ensure Python 3 compatibility
-- Person Version Read
 - Person Update
 - Relationship Read
 - Relationship Update

familysearch/familytree_v2.py

@@ -57,6 +57,22 @@ def person(self, person_id=None, options={}, **kw_options):
         else:
             return response
 
+    def version(self, person_id):
+        """
+        Read the latest version of a person or list of persons from the family tree.
+        """
+        if isinstance(person_id, list):
+            person_id = ','.join(person_id)
+        url = self.familytree_base + 'version'
+        if person_id:
+            url = self._add_subpath(url, person_id)
+        response = json.load(self._request(url))['versions']
+        response = self._remove_nones(response)
+        if len(response) == 1:
+            return response[0]
+        else:
+            return response
+
     def pedigree(self, person_id=None, options={}, **kw_options):
         """
         Get a pedigree for the given person or list of persons from the family tree.