Consistent Database Method Names

Development
1

Gramps has a number of methods for getting data from the database. The available methods are a combination of

  • record identifier
    • handle
    • gramps_id
  • result type
    • object
    • DataDict
    • iterator of object, handle or data

but there is little consistency in the naming of these methods. This was previously discussed in late 2024 but no consensus was reached. Personally, I find this lack of consistency frustrating so I’m picking up the baton in the hope that we can reach a consensus this time.

Proposal

Current Proposed
get_person_from_handle get_person
get_person_from_gramps_id get_person_from_gramps_id
get_raw_person_data get_person_data
_get_raw_person_from_id_data get_person_data_from_gramps_id
iter_person_handles iter_person_handles
iter_people iter_person
_iter_raw_person_data iter_person_data

with similar changes for the other object types.

Summary of changes

  1. Two internal methods are made public (_get_raw_person_from_id_data, _iter_raw_person_data)
    There does not appear to be a reason for these methods to remain internal
  2. The singular form is used in method names (person rather than people).
    Hopefully making it easier for non-native English speakers
  3. handle is the primary record identifier and so _from_handle is dropped from method names.
    Less typing is always a good thing
  4. _raw is dropped from methods.
    It is superfluous given _data is also present in the method name.

Proposed timeline

Gramp version Status
6.1 Proposed methods implemented. Current methods remain available. Codebase left as-is.
6.2 Codebase updated to use proposed methods. Current methods deprecated but still available. All addons updated.
6.3 Deprecated methods removed.

6.1, 6.2, 6.3 just represent future releases. The actual version numbers may vary.
A staggered implementation will make it easier for any addon developers that support multiple gramps versions from a single code base. I welcome proposals to move more quickly if this is not a concern.

Previous

We could look to combine handle and gramps_id forms of methods either via @singledispatch or parameter type inspection i.e. if isinstance(key, PersonHandle): ... elif isinstance(key, PersonGrampsID): ... Personally I’d prefer to make some improvement now.

Your comments sought.

1 Like
2

Where does the Simple Access fit into this discussion of harmonizing method naming?

3

Great question @emyoulation . The good news is that the SimpleAccess API will not be impacted at all. Internally, the SimpleAccess class is using the “Current” methods from my table. In my timeline, during 6.2, this would be updated to use the “Proposed” methods. That’s a purely internal change and any reports using SimpleAccess should continue to work with no change.

1 Like