Hierarchical Place Structure

From Gramps
Jump to: navigation, search
Feature add to Gramps version 4.1

Place objects have been arranged into a hierarchy in Gramps version 4.1

New Place Structure

Place object

Instead of containing a main location, place objects are now arranged into a hierarchy. They contain four new fields:

  • name
  • type
  • placeref_list (list of parent places)
  • code (postal code / phone number)

Places are linked to parent places via PlaceRef objects. These contain a handle to a parent place and a Date. Places may have multiple parent places, or no parent place if they are top-level places. The first entry in the list is deemed to be the primary parent.

The type of a place is stored in a GrampsType called PlaceType.

The code field is provided to store a code associated with the place. This could be a country code, state abbreviation, Chapman county code etc... The database upgrade will assign the postal code and/or phone number to this field.

Utility functions

To obtain a location description for a place, a path to a top-level place must be traversed. There are a few utility functions in gen.utils.location for this purpose:

get_location_list(db, place)

Traverses the hierarchy following the primary parent and returns a list of place names. This can then be formatted using the join method.

', '.join(get_location_list(db, place))

get_main_location(db, place)

This also traverses the hierarchy following the primary parent, but returns a dictionary of place types and names. This can be used to extract a particular place type.

get_main_location(db, place).get(PlaceType.CITY)

get_locations(db, place)

Determines each possible route up the place hierarchy, and returns a list containing dictionaries of place types and names. Each list element represents a separate path up the hierarchy.


The Place tree view displays the place hierarchy using primary parents. A new tree cursor provides the view with place records in top-down order, which greatly simplifies the code. Every node in the tree view represents a Gramps place.

To find the children of a place, the existing find_backlink_handles database method can be used. If only primary parents should be followed a new find_place_child_handles method has been provided.

Both the place tree cursor and find_place_child_handles method use an index on the primary parent called place_parent.


The place object still contains a title field. This contains a full description of the place and is used in most reports.

Alternate locations have not been converted into new places in the hierarchy.

What next?

  • Do we want to use the new widgets demonstrated in the prototype?
  • Should we support Gedcom 5.5EL? See Feature Request:688

See also