View source for Specification:Relationship Calculator

{{languages|Specification:Relationship Calculator}}

Rationale and requirements for the [[Gramps_{{man version}}_Wiki_Manual_-_Tools#Relationship_Calculator|Relationship Calculator]] plugin for Gramps, and its localization.

==Why have different relationship calculators?==
Different cultures and regions tend to view relationships in different ways. In the United States (and probably other English speaking regions), you can encounter a third cousin, twice removed, which in other regions is meaningless. Other cultures have different terms for your mother's grandfather and your father's grandfather, while English speaking regions would refer to both as a great-grandfather.

By providing relationship calculators, several problems are resolved.
* Meaningful relation descriptions are returned localized for the user's region.
* The relationship calculator plugin can return the relationship outside of the Relationship Calculator, allowing relationships to be used in reports and other areas.
* Translators do not have to worry about trying to translate strings such as "third cousin twice removed" into a local phrase that has no equivalent.

==How to write a relationship calculator==
===For Gramps 6.x.x===
The relationship calculator Logic is the same as Gramps version 5.x.

Here are the rules the language-specific plugins must obey to be compatible with the [https://gramps-project.org/docs/relationship.html framework]:
# You need to make localized versions of the methods:
:#<code>get_single_relationship_string</code> (used on ''[https://github.com/gramps-project/gramps/blob/58cab54568fc271ff26fc31127f4aa465833a20d/gramps/plugins/quickview/all_relations.py#L271 Quick Views]/Reports'')
:#<code>get_sibling_relationship_string</code> (used on ''[[Gramps_6.0_Wiki_Manual_-_Tools#Relationship_Calculator|Relationship Calculator]]'' tool and on ''[[Gramps_6.0_Wiki_Manual_-_Settings#Display_Options|Status Bar]]'')
:#<code>get_plural_relationship_string</code> (used on ''[[Gramps_6.0_Wiki_Manual_-_Reports_-_part_6#Kinship_Report|Kinship Report]]'')
:#<code>get_partner_relationship_string</code> - only make a localized version of this if the gettext translation present in [https://github.com/gramps-project/gramps/blob/master/gramps/gen/relationship.py <code>Relationship.py</code>] is not sufficient

{{man tip|Note|that the signature of the methods must be identical to the ones in <code>[{{Code Base}}gramps/gen/relationship.py gramps/gen/relationship.py]</code>}}

All other methods are unique to the English module, and should not be overwritten. You can however define your own helper functions like present in <code>relationship.py</code>, eg <code>_get_father()</code>. Helper functions start with a <code>_</code> and are not used outside of the Relationship class module.

Text strings returned by the function should be in the UNICODE character set. GNOME expects all displayed strings to be UNICODE characters, and most report formats use UNICODE. While it may be tempting to use ISO-8859 or other character sets, these will not display correctly and will cause errors.

The relationship plugin must be [[GEPS 014: Plugin registration and management|registered]] in the plugin system. In short, you have to edit the file <code>[{{Code Base}}gramps/plugins/rel/relplugins.gpr.py relplugins.gpr.py]</code> in the directory <code>gramps/tree/master/gramps/plugins/rel</code>. Follow the model of any of the other languages, and fill in all the possible language identifiers that '''may possibly''' be associated with your language: for example, different systems use <code>ru</code>, <code>RU</code>, <code>ru_RU</code>, <code>koi8r</code>, <code>ru_koi8r</code>, <code>russian</code>, <code>Russian</code>, <code>ru_RU.koi8r</code>, etc. to identify the Russian language.

That's it for the requirements. The example <code>relcalc</code> plugins can be found in <code>[{{Code Base}}gramps/gen/relationship.py gramps/gen/relationship.py]</code> and <code>[{{Code Base}}/gramps/plugins/rel/rel_it.py gramps/plugins/rel/rel_it.py]</code> or <code>[{{Code Base}}gramps/plugins/rel/rel_nl.py gramps/plugins/rel/rel_nl.py]</code>.

<!--
To begin to make a copy of relationship.py and rename to rel_xx.py (where xx is the two letter language iso code name) and move the file to the same folder as the other language handlers in gramps/plugins/rel/ 
-->

====Tests====

You are further strongly advised to run the same tests as are present at the bottom of those files. If you have obtained Gramps Git in <code>/home/me/Gramps</code>, then you can run the test for eg. rel_it.py as follows in a terminal:

 cd /home/me/Gramps
 export PYTHONPATH=/home/me/Gramps/gramps
 python gramps/plugins/rel/rel_it.py

You could also run [[Programming_Guidelines#Pylint|pylint]] as follows in a terminal
 
 cd /home/me/Gramps
 export PYTHONPATH=/home/me/Gramps/gramps
 pylint gramps/plugins/rel/rel_it.py > /home/me/Gramps/gramps/plugins/rel/it.txt

===For Gramps 5.x.x===
<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle">'''«Click to expand»'''</div>
<div class="mw-collapsible-content">
<!-- Collapsible content goes here -->
The relationship calculator Logic is the same as Gramps version 4.x.

Here are the rules the language-specific plugins must obey to be compatible with the [https://gramps-project.org/docs/relationship.html framework]:
# You need to make localized versions of the methods:
:#<code>get_single_relationship_string</code> (used on ''[https://github.com/gramps-project/gramps/blob/58cab54568fc271ff26fc31127f4aa465833a20d/gramps/plugins/quickview/all_relations.py#L271 Quick Views]/Reports'')
:#<code>get_sibling_relationship_string</code> (used on ''[[Gramps_5.2_Wiki_Manual_-_Tools#Relationship_Calculator|Relationship Calculator]]'' tool and on ''[[Gramps_5.2_Wiki_Manual_-_Settings#Display_Options|Status Bar]]'')
:#<code>get_plural_relationship_string</code> (used on ''[[Gramps_5.2_Wiki_Manual_-_Reports_-_part_6#Kinship_Report|Kinship Report]]'')
:#<code>get_partner_relationship_string</code> - only make a localized version of this if the gettext translation present in [https://github.com/gramps-project/gramps/blob/master/gramps/gen/relationship.py <code>Relationship.py</code>] is not sufficient

{{man tip|Note|that the signature of the methods must be identical to the ones in <code>[{{Code Base}}gramps/gen/relationship.py gramps/gen/relationship.py]</code>}}

All other methods are unique to the English module, and should not be overwritten. You can however define your own helper functions like present in <code>relationship.py</code>, eg <code>_get_father()</code>. Helper functions start with a <code>_</code> and are not used outside of the Relationship class module.

Text strings returned by the function should be in the UNICODE character set. GNOME expects all displayed strings to be UNICODE characters, and most report formats use UNICODE. While it may be tempting to use ISO-8859 or other character sets, these will not display correctly and will cause errors.

The relationship plugin must be [[GEPS 014: Plugin registration and management|registered]] in the plugin system. In short, you have to edit the file <code>[{{Code Base}}gramps/plugins/rel/relplugins.gpr.py relplugins.gpr.py]</code> in the directory <code>gramps/tree/master/gramps/plugins/rel</code>. Follow the model of any of the other languages, and fill in all the possible language identifiers that '''may possibly''' be associated with your language: for example, different systems use <code>ru</code>, <code>RU</code>, <code>ru_RU</code>, <code>koi8r</code>, <code>ru_koi8r</code>, <code>russian</code>, <code>Russian</code>, <code>ru_RU.koi8r</code>, etc. to identify the Russian language.

That's it for the requirements. The example <code>relcalc</code> plugins can be found in <code>[{{Code Base}}gramps/gen/relationship.py gramps/gen/relationship.py]</code> and <code>[{{Code Base}}/gramps/plugins/rel/rel_it.py gramps/plugins/rel/rel_it.py]</code> or <code>[{{Code Base}}gramps/plugins/rel/rel_nl.py gramps/plugins/rel/rel_nl.py]</code>.

<!--
To begin to make a copy of relationship.py and rename to rel_xx.py (where xx is the two letter language iso code name) and move the file to the same folder as the other language handlers in gramps/plugins/rel/ 
-->

====Tests====

You are further strongly advised to run the same tests as are present at the bottom of those files. If you have obtained Gramps Git in <code>/home/me/Gramps</code>, then you can run the test for eg. rel_it.py as follows in a terminal:

 cd /home/me/Gramps
 export PYTHONPATH=/home/me/Gramps/gramps
 python gramps/plugins/rel/rel_it.py

You could also run [[Programming_Guidelines#Pylint|pylint]] as follows in a terminal
 
 cd /home/me/Gramps
 export PYTHONPATH=/home/me/Gramps/gramps
 pylint gramps/plugins/rel/rel_it.py > /home/me/Gramps/gramps/plugins/rel/it.txt
    </div>
</div>
{{-}}
===For Gramps 4.x.x===
<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle">'''«Click to expand»'''</div>
<div class="mw-collapsible-content">
<!-- Collapsible content goes here -->
The relationship calculator Logic is the same as Gramps version 3.0. Only paths and filename etc have been updated due to the Code reorganisation.

Here are the rules the language-specific plugins must obey to be compatible with the [https://gramps-project.org/docs/relationship.html framework]:
# You need to make localized versions of the methods:
:#get_single_relationship_string (used on ''quick report'')
:#get_sibling_relationship_string (used on ''RelCalc'' tool and on ''Status Bar'')
:#get_plural_relationship_string (used on ''kinship report'')
:#get_partner_relationship_string - only make a localized version of this if the gettext translation present in Relationship.py is not sufficient

:Note that the signature of the methods must be identical to the ones in [{{Code Base}}gramps/gen/relationship.py gramps/gen/relationship.py]

All other methods are unique to the English module, and should not be overwritten. You can however define your own helper functions like present in relationship.py, eg _get_father(). Helper functions start with a _ and are not used outside of the Relationship class module.

Text strings returned by the function should be in the UNICODE character set. GNOME expects all displayed strings to be UNICODE characters, and most report formats use UNICODE. While it may be tempting to use ISO-8859 or other character sets, these will not display correctly and will cause errors.

The relationship plugin must be [[GEPS 014: Plugin registration and management|registered]] in the plugin system. In short, you have to edit the file <code>[{{Code Base}}gramps/plugins/rel/relplugins.gpr.py relplugins.gpr.py]</code> in the directory <code>gramps/tree/master/gramps/plugins/rel</code>. Follow the model of any of the other languages, and fill in all the possible language identifiers that '''may possibly''' be associated with your language: for example, different systems use <code>ru</code>, <code>RU</code>, <code>ru_RU</code>, <code>koi8r</code>, <code>ru_koi8r</code>, <code>russian</code>, <code>Russian</code>, <code>ru_RU.koi8r</code>, etc. to identify the Russian language.

That's it for the requirements. The example <code>relcalc</code> plugins can be found in <code>[{{Code Base}}gramps/gen/relationship.py gramps/gen/relationship.py]</code> and <code>[{{Code Base}}/gramps/plugins/rel/rel_it.py gramps/plugins/rel/rel_it.py]</code> or <code>[{{Code Base}}gramps/plugins/rel/rel_nl.py gramps/plugins/rel/rel_nl.py]</code>.

====Tests====

You are further strongly advised to run the same tests as are present at the bottom of those files. If you have obtained Gramps Git in <code>/home/me/Gramps</code>, then you can run the test for eg. rel_it.py as follows in a terminal:

 cd /home/me/Gramps
 export PYTHONPATH=/home/me/Gramps/gramps
 python gramps/plugins/rel/rel_it.py

You could also run [[Programming_Guidelines#Pylint|pylint]] as follows in a terminal
 
 cd /home/me/Gramps
 export PYTHONPATH=/home/me/Gramps/gramps
 pylint gramps/plugins/rel/rel_it.py > /home/me/Gramps/gramps/plugins/rel/it.txt
    </div>
</div>
{{-}}
===For Gramps 3.x.x===
<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle">'''«Click to expand»'''</div>
<div class="mw-collapsible-content">
<!-- Collapsible content goes here -->
The relationship calculator changed for version 3.0. Logic has been separated from translation, which will allow code improvements to occur more easily, being available immediately in all translated modules.

Here are the rules the language-specific plugins must obey to be compatible with the [http://www.gramps-project.org/docs/relationship.html framework]:
# You need to make localized versions of the methods:
:#get_single_relationship_string (used on ''quick report'')
:#get_sibling_relationship_string (used on ''RelCalc'' tool and on ''Status Bar'')
:#get_plural_relationship_string (used on ''kinship report'')
:#get_partner_relationship_string - only make a localized version of this if the gettext translation present in Relationship.py is not sufficient

:Note that the signature of the methods must be identical to the ones in Relationship.py
All other methods are unique to the English module, and should not be overwritten. You can however define your own helper functions like present in Relationship.py, eg _get_father(). Helper functions start with a _ and are not used outside of the Relationship class module.

Text strings returned by the function should be in the UNICODE character set. GNOME expects all displayed strings to be UNICODE characters, and most report formats use UNICODE. While it may be tempting to use ISO-8859 or other character sets, these will not display correctly and will cause errors.

The relationship plugin must be [[GEPS 014: Plugin registration and management|registered]] in the plugin system. In short, you have to edit the file <code>relplugins.gpr.py</code> in the directory <code>src/plugins/rel</code>. Follow the model of any of the other languages, and fill in all the possible language identifiers that '''may possibly''' be associated with your language: for example, different systems use <code>ru</code>, <code>RU</code>, <code>ru_RU</code>, <code>koi8r</code>, <code>ru_koi8r</code>, <code>russian</code>, <code>Russian</code>, <code>ru_RU.koi8r</code>, etc. to identify the Russian language.

That's it for the requirements. The example <code>relcalc</code> plugins can be found in <code>src/Relationship.py</code> and <code>src/plugins/rel/rel_it.py</code> or <code>src/plugins/rel/rel_nl.py</code>.

====Tests====

You are further strongly adviced to run the same tests as are present at the bottom of those files. If you have obtained Gramps Git in <code>/home/me/Gramps</code>, then you can run the test for eg. rel_it.py as follows in a terminal:

 cd /home/me/Gramps
 export PYTHONPATH=/home/me/Gramps/src 
 python src/plugins/rel/rel_it.py

You could also run [[Programming_Guidelines#Pylint|pylint]] as follows in a terminal
 
 cd /home/me/Gramps
 export PYTHONPATH=/home/me/Gramps/src 
 pylint src/plugins/rel/rel_it.py > /home/me/Gramps/src/plugins/rel/it.txt
    </div>
</div>
{{-}}
===For Gramps 2.2.x===
<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle">'''«Click to expand»'''</div>
<div class="mw-collapsible-content">
<!-- Collapsible content goes here -->The framework for relationship calculator plugins is in place. Here are the rules the language-specific plugins must obey to be compatible with the framework:
# The relationship plugins (here and below referred to as <code>rel</code> plugins) must define a class that can be instantiated with the [http://www.gramps-project.org/docs/gen/gen_db.html#module-gen.db.base GrampsDbBase] instance as its argument and that has a <code>get_relationship()</code> method obeying the following specifications:
#* The <code>get_relationship()</code> method takes '''two''' input arguments, which are two instances of the [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gen.lib.person Person] class. To be determined is the relationship of the second person to the first person.
#* The <code>get_relationship()</code> method returns a tuple with '''two''' values:
#*# The string of the relationship (e.g. "father", or "grandson")
#*# The list of the closest common ancestors of these two persons.
#* For the sake of the following example, assume that the above function is defined in <code>src/plugins/rel_xx.py</code> (where <code>xx</code> is your language code), and it's name is <code>get_relationship(first_person,second_person)</code>. Also assume that it returns a pair of values: <code>(rel_string, acnestor_list)</code>.
#* Text strings returned by the function should be in the UNICODE character set. GNOME expects all displayed strings to be UNICODE characters, and most report formats use UNICODE. While it may be tempting to use ISO-8859 or other character sets, these will not display correctly and will cause errors.
# The relationship plugin must register itself with the plugin system as the <code>relcalc</code> tool. This is done by inserting the following code at the end of your <code>rel_xx.py</code> file:

     from PluginMgr import register_relcalc
     register_relcalc(RelationshipCalculatorClass,["xx","XX","xx_YY","xxxxxx","Xxxxxx","Xxxxxxx_xx"])

:where <code>RelationshipCalculatorClass</code> is the class whose method is the <code>get_relationship()</code> and the items in quotes are language identifiers that '''may possibly''' be associated with your language. For example, different systems use <code>ru</code>, <code>RU</code>, <code>ru_RU</code>, <code>koi8r</code>, <code>ru_koi8r</code>, <code>russian</code>, <code>Russian</code>, <code>ru_RU.koi8r</code>, etc. to identify the Russian language.


That's it for the requirements. The example <code>relcalc</code> plugins can be found in <code>src/Relationship.py</code> and <code>src/plugins/rel_ru.py</code>.
    </div>
</div>
{{-}}

==See also==
*[[Handler List]]
*[[Calendar tools holidays]]

{{languages|Specification:Relationship Calculator}}

[[Category:Translators/Categories]]
[[Category:Developers/General]]
[[Category:Plugins]]
[[Category:Tools]]
[[Category:GEPS|C]]