From ceb3f442056047b64f2209b1d4ea527aa9401f8f Mon Sep 17 00:00:00 2001 From: Nick Hall Date: Tue, 12 Nov 2013 21:43:38 +0000 Subject: [PATCH] Improve gen.utils documentation --- docs/gen/gen_utils.rst | 109 ++++++++++++++++++------------ gramps/gen/utils/alive.py | 4 +- gramps/gen/utils/callback.py | 55 +++++++-------- gramps/gen/utils/configmanager.py | 62 +++++++++-------- gramps/gen/utils/db.py | 60 ++++++++-------- gramps/gen/utils/grampslocale.py | 64 ++++++++++-------- gramps/gen/utils/place.py | 56 +++++++++------ 7 files changed, 227 insertions(+), 183 deletions(-) diff --git a/docs/gen/gen_utils.rst b/docs/gen/gen_utils.rst index 14715f62a..01eab028f 100644 --- a/docs/gen/gen_utils.rst +++ b/docs/gen/gen_utils.rst @@ -4,12 +4,12 @@ The :mod:`gramps.gen.utils` Module .. automodule:: gramps.gen.utils -Utils +********************************** +Utilities +********************************** + +Callback ==================================== -.. automodule:: gramps.gen.utils.alive - :members: - :undoc-members: - :show-inheritance: .. automodule:: gramps.gen.utils.callback :members: :undoc-members: @@ -18,7 +18,10 @@ Utils :members: :undoc-members: :show-inheritance: -.. automodule:: gramps.gen.utils.cast + +Configuration +==================================== +.. automodule:: gramps.gen.utils.configmanager :members: :undoc-members: :show-inheritance: @@ -26,7 +29,10 @@ Utils :members: :undoc-members: :show-inheritance: -.. automodule:: gramps.gen.utils.configmanager + +Database +==================================== +.. automodule:: gramps.gen.utils.alive :members: :undoc-members: :show-inheritance: @@ -34,45 +40,62 @@ Utils :members: :undoc-members: :show-inheritance: -.. automodule:: gramps.gen.utils.file - :members: - :undoc-members: - :show-inheritance: -.. automodule:: gramps.gen.utils.grampslocale - :members: - :undoc-members: - :show-inheritance: -.. automodule:: gramps.gen.utils.id - :members: - :undoc-members: - :show-inheritance: -.. automodule:: gramps.gen.utils.image - :members: - :undoc-members: - :show-inheritance: -.. automodule:: gramps.gen.utils.keyword - :members: - :undoc-members: - :show-inheritance: -.. automodule:: gramps.gen.utils.lds - :members: - :undoc-members: - :show-inheritance: -.. automodule:: gramps.gen.utils.maclocale - :members: - :undoc-members: - :show-inheritance: -.. automodule:: gramps.gen.utils.place - :members: - :undoc-members: - :show-inheritance: -.. automodule:: gramps.gen.utils.string - :members: - :undoc-members: - :show-inheritance: .. automodule:: gramps.gen.utils.unknown :members: :undoc-members: :show-inheritance: +File +==================================== +.. automodule:: gramps.gen.utils.file + :members: + :undoc-members: + :show-inheritance: +Image +==================================== +.. automodule:: gramps.gen.utils.image + :members: + :undoc-members: + :show-inheritance: + +Locale +==================================== +.. automodule:: gramps.gen.utils.grampslocale + :members: + :undoc-members: + :show-inheritance: +.. automodule:: gramps.gen.utils.maclocale + :members: + :undoc-members: + :show-inheritance: +.. automodule:: gramps.gen.utils.keyword + :members: + :undoc-members: + :show-inheritance: + +Place +==================================== +.. automodule:: gramps.gen.utils.place + :members: + :undoc-members: + :show-inheritance: + +Other +==================================== +.. automodule:: gramps.gen.utils.cast + :members: + :undoc-members: + :show-inheritance: +.. automodule:: gramps.gen.utils.id + :members: + :undoc-members: + :show-inheritance: +.. automodule:: gramps.gen.utils.lds + :members: + :undoc-members: + :show-inheritance: +.. automodule:: gramps.gen.utils.string + :members: + :undoc-members: + :show-inheritance: diff --git a/gramps/gen/utils/alive.py b/gramps/gen/utils/alive.py index eaa732405..bc3c44d04 100644 --- a/gramps/gen/utils/alive.py +++ b/gramps/gen/utils/alive.py @@ -484,8 +484,8 @@ def probably_alive(person, db, be alive. :param current_date: a date object that is not estimated or modified - (defaults to today) - :param limit: number of years to check beyond death_date + (defaults to today) + :param limit: number of years to check beyond death_date :param max_sib_age_diff: maximum sibling age difference, in years :param max_age_prob_alive: maximum age of a person, in years :param avg_generation_gap: average generation gap, in years diff --git a/gramps/gen/utils/callback.py b/gramps/gen/utils/callback.py index f1d031903..d1c3a6e2a 100644 --- a/gramps/gen/utils/callback.py +++ b/gramps/gen/utils/callback.py @@ -22,19 +22,18 @@ # $Id$ """ - Introduction - ============ - - Gramps is devided into two parts. The database code, that does not - require any particular GUI libraries, and the gtk-based UI code - that requires gtk and gnome libraries. The gtk-based code can use - the gobject signal support to manage callback signals but the database - code can not. +**Introduction** - The module provides a subset of the signal mechanisms that are available - from the gobject framework. It enables the database code to use signals - to communicate events to any callback methods in either the database code - or the UI code. +Gramps is devided into two parts. The database code, that does not +require any particular GUI libraries, and the gtk-based UI code +that requires gtk and gnome libraries. The gtk-based code can use +the gobject signal support to manage callback signals but the database +code can not. + +The module provides a subset of the signal mechanisms that are available +from the gobject framework. It enables the database code to use signals +to communicate events to any callback methods in either the database code +or the UI code. """ import sys import types @@ -54,11 +53,10 @@ class Callback(object): """ Callback and signal support objects. - Declaring signals - ================= + **Declaring signals** Classes that want to emit signals need to inherit from the - DBCallback class and ensure that its __init__ method + DBCallback class and ensure that its :meth:`__init__` method is called. They then need to declare the signals that they can emit and the types of each callbacks arguments. For example:: @@ -85,8 +83,7 @@ class Callback(object): signal names in subclasses are not alowed. - Emitting signals - ================ + **Emitting signals** Signals are emitted using the emit method. e.g.:: @@ -96,8 +93,7 @@ class Callback(object): The parameters are passed as a tuple so a single parameter must be passed as a 1 element tuple. - Connecting callbacks to signals - =============================== + **Connecting callbacks to signals** Attaching a callback to the signals is similar to the gtk connect methods. e.g.:: @@ -119,8 +115,7 @@ class Callback(object): t.connect('test-signal', r.cb_func) - Disconnecting callbacks - ======================= + **Disconnecting callbacks** If you want to disconnect a callback from a signals you must remember the key returned from the connect call. This key can be passed to the disconnect @@ -144,13 +139,12 @@ class Callback(object): t.disconnect(key) - Stopping and starting signals - ============================= + **Stopping and starting signals** Signals can be blocked on a per instance bassis or they can be blocked - for all instances of the Callback class. disable_signals() can - be used to block the signals for a single instance and disable_all_signals() - can be used to block signals for the class: + for all instances of the Callback class. :meth:`disable_signals` can + be used to block the signals for a single instance and + :meth:`disable_all_signals` can be used to block signals for the class: e.g.:: @@ -190,14 +184,13 @@ class Callback(object): Any signals emitted whilst signals are blocked will be lost. - Debugging signal callbacks - ========================== + **Debugging signal callbacks** To help with debugging the signals and callbacks you can turn on lots of logging information. To switch on logging for a single - instance call self.enable_logging(), to switch it off again call - self.disable_logging(). To switch on logging for all instance + instance call :meth:`enable_logging`, to switch it off again call + :meth:`disable_logging`. To switch on logging for all instance you can toggle Callback.__LOG_ALL to True. """ @@ -277,7 +270,7 @@ class Callback(object): with the signal is emitted. The callable must accept the argument types declared in the signals signature. - returns a unique key that can be passed to disconnect(). + returns a unique key that can be passed to :meth:`disconnect`. """ # Check that signal exists. if signal_name not in self.__signal_map: diff --git a/gramps/gen/utils/configmanager.py b/gramps/gen/utils/configmanager.py index 3a457bf03..b81874e16 100644 --- a/gramps/gen/utils/configmanager.py +++ b/gramps/gen/utils/configmanager.py @@ -23,7 +23,7 @@ # $Id$ """ -This package implements access to GRAMPS configuration. +This package implements access to Gramps configuration. """ #--------------------------------------------------------------- @@ -79,7 +79,7 @@ class ConfigManager(object): Configure manager constructor takes an optional filename, and plugin path. - The data dictionary stores the settings: + The data dictionary stores the settings:: self.data[section][setting] = value @@ -93,11 +93,11 @@ class ConfigManager(object): simple types. The default values are given in Python code and stored here - on start-up: + on start-up:: self.default[section][setting] = default_value - Callbacks are stored as callables here: + Callbacks are stored as callables here:: self.callbacks[section][setting] = (id, func) @@ -105,8 +105,8 @@ class ConfigManager(object): is stored as self.filename. However, you can save to another filename using self.save(otherfilename). - filename (if given) is a fullpath. - plugins (if given) is a relative path to filename. + :param filename: (if given) is a fullpath. + :param plugins: (if given) is a relative path to filename. """ self._cb_id = 0 # callback id counter @@ -124,36 +124,40 @@ class ConfigManager(object): """ Register a plugin manager. - name is used as the key of the config manager singleton. It is - also be used as the base filename (unless an override is given, - or use_config_path or use_plugins_path is True). + :param name: is used as the key of the config manager singleton. It is + also be used as the base filename (unless an override is + given, or use_config_path or use_plugins_path is True). + :param override: is used to override the default location of the .ini + file. + :param use_config_path: if True, use this ConfigManager's path as the + new manager's path, ignoring any path given in + override. + + Override is either: - override is either: - a full path+filename ending in .ini - a filename ending in .ini - a dir path to put ini file into - a full path+filename to get dir to put ini file into - a ConfigManager instance - If use_config_path is True, use this ConfigManager's path as - the new manager's path, ignoring any path given in override. + Examples:: - Examples: - >>> config.register_manager("Simple", use_plugins_path=False) - # will use the calling programs directory, and "Simple.ini" - >>> config.register_manager("Simple", __file__, - use_plugins_path=False) - # will use the __file__'s directory, and "Simple.ini" - >>> config.register_manager("Simple", "c:\\temp", - use_plugins_path=False) - # will use the given directory, "c:\\temp\\Simple.ini" - >>> config.register_manager("Simple", use_config_path=True) - # will use config's path: ~/.gramps/gramps32/Simple.ini - >>> config.register_manager("Simple", "Other.ini") - # will use config + plugins path: ~/.gramps/gramps32/plugins/Other.ini - >>> config.register_manager("Simple", "/tmp/Other.ini", - use_plugins_path=False) - # will use /tmp/Other.ini + >>> config.register_manager("Simple", use_plugins_path=False) + # will use the calling programs directory, and "Simple.ini" + >>> config.register_manager("Simple", __file__, + use_plugins_path=False) + # will use the __file__'s directory, and "Simple.ini" + >>> config.register_manager("Simple", "c:\\temp", + use_plugins_path=False) + # will use the given directory, "c:\\temp\\Simple.ini" + >>> config.register_manager("Simple", use_config_path=True) + # will use config's path: ~/.gramps/gramps32/Simple.ini + >>> config.register_manager("Simple", "Other.ini") + # will use config + plugins path: ~/.gramps/gramps32/plugins/Other.ini + >>> config.register_manager("Simple", "/tmp/Other.ini", + use_plugins_path=False) + # will use /tmp/Other.ini """ if isinstance(override, STRTYPE): # directory or filename if override: @@ -510,7 +514,7 @@ class ConfigManager(object): def set(self, key, value): """ Set the setting's value. There are only two ways to get into - the data dictionary: via the load() method that reads a file, + the data dictionary: via the :meth:`load` method that reads a file, or from this method. """ if "." in key: diff --git a/gramps/gen/utils/db.py b/gramps/gen/utils/db.py index 21f063d95..9fe4a3bd7 100644 --- a/gramps/gen/utils/db.py +++ b/gramps/gen/utils/db.py @@ -94,9 +94,11 @@ def get_death_or_fallback(db, person, format=None): def get_age(db, person, fallback=True, calendar="gregorian"): """ - Compute the age of person. Allow fallback events if fallback=True - person : person handle or person object - Return: tuple of year, month day if valid, None otherwise + Compute the age of person. + + :param person: person handle or person object + :param fallback: Allow fallback events if True + :returns: tuple of year, month day if valid, None otherwise """ birth = None death = None @@ -136,8 +138,9 @@ def get_age(db, person, fallback=True, calendar="gregorian"): def get_timeperiod(db, person): """ Compute the timeperiod a person lived in - person : person handle or person object - Return: the year, None otherwise + + :param person: person handle or person object + :returns: the year, None otherwise """ if isinstance(person, str): # a handle is passed @@ -254,7 +257,7 @@ def get_participant_from_event(db, event_handle, all_=False): Obtain the first primary or family participant to an event we find in the database. Note that an event can have more than one primary or family participant, only one is returned, adding ellipses if there are - more. If the all_ parameter is true a comma-space separated string with + more. If the all\_ parameter is true a comma-space separated string with the names of all primary participants is returned and no ellipses is used. """ participant = "" @@ -593,31 +596,32 @@ def get_source_and_citation_referents(source_handle, db): This function finds all primary objects that refer (directly or through secondary child-objects) to a given source handle in a given database. - Objects -> Citations -> Source - e.g. - Media object M1 -> Citation C1 -> Source S1 - Media object M2 -> Citation C1 -> Source S1 - Person object P1 -> Citation C2 -> Source S1 + | Objects -> Citations -> Source + | e.g. + | Media object M1 -> Citation C1 -> Source S1 + | Media object M2 -> Citation C1 -> Source S1 + | Person object P1 -> Citation C2 -> Source S1 The returned structure is rather ugly, but provides all the information in a way that is consistent with the other Util functions. - ( - tuple of objects that refer to the source - only first element is present - ([C1, C2],), - list of citations with objects that refer to them - [ - (C1, - tuple of reference lists - P, F, E, Pl, S, M, R - ([], [], [], [], [], [M1, M2]. []) - ) - (C2, - tuple of reference lists - P, F, E, Pl, S, M, R - ([P1], [], [], [], [], []. []) - ) - ] - ) + + | ( + | tuple of objects that refer to the source - only first element is present + | ([C1, C2],), + | list of citations with objects that refer to them + | [ + | (C1, + | tuple of reference lists + | P, F, E, Pl, S, M, R + | ([], [], [], [], [], [M1, M2]. []) + | ) + | (C2, + | tuple of reference lists + | P, F, E, Pl, S, M, R + | ([P1], [], [], [], [], []. []) + | ) + | ] + | ) """ the_lists = get_source_referents(source_handle, db) LOG.debug('source referents %s' % [the_lists]) diff --git a/gramps/gen/utils/grampslocale.py b/gramps/gen/utils/grampslocale.py index 268074de1..5428fcca0 100644 --- a/gramps/gen/utils/grampslocale.py +++ b/gramps/gen/utils/grampslocale.py @@ -145,18 +145,18 @@ class GrampsLocale(object): new GrampsLocale instance with the specified parameters, but any parameters left out will be filled in from the first instance. - @localedir: The full path to the top level directory containing - the translation files. Defaults to sys.prefix/share/locale. + :param localedir: The full path to the top level directory containing the + translation files. Defaults to sys.prefix/share/locale. - @lang: A single locale value which is used for unset locale.LC_FOO - settings. + :param lang: A single locale value which is used for unset locale.LC_FOO + settings. - @domain: The name of the applicable translation file. The default is - "gramps", indicating files in LC_MESSAGES named gramps.mo. + :param domain: The name of the applicable translation file. The default is + "gramps", indicating files in LC_MESSAGES named gramps.mo. - @languages: String with a ':'-separated list of two or five character - codes corresponding to subidrectries in the localedir, - e.g.: "fr" or "zh_CN". + :param languages: String with a ':'-separated list of two or five character + codes corresponding to subidrectries in the localedir, + e.g.: "fr" or "zh_CN". """ DEFAULT_TRANSLATION_STR = "default" @@ -632,7 +632,8 @@ class GrampsLocale(object): cached, set it from datehandler.LANG_TO_DISPLAY. If one isn't available for the selected locale, attempt to fall back on the first_instance's locale before settling on the 'C' displayer. - NB: This is the getter for the date_displayer property + + .. note:: This is the getter for the date_displayer property """ if self._dd: return self._dd @@ -665,7 +666,8 @@ class GrampsLocale(object): cached, set it from datehandler.LANG_TO_PARSER. If one isn't available for the selected locale, attempt to fall back on the first_instance's locale before settling on the 'C' parser. - NB: This is the getter for the date_parser property + + .. note:: This is the getter for the date_parser property """ if self._dp: return self._dp @@ -712,18 +714,19 @@ class GrampsLocale(object): """ Get a translator for an addon. - filename - filename of a file in directory with full path, or - None to get from self. - domain - the name of the .mo file under the LANG/LC_MESSAGES dir - languages - a list of languages to force - returns - a gettext.translation object + :param filename: filename of a file in directory with full path, or + None to get from self. + :param domain: the name of the .mo file under the LANG/LC_MESSAGES dir + :param languages: a list of languages to force + :returns: a gettext.translation object + + Example:: - Example: _ = glocale.get_addon_translator(languages=["fr_BE.utf8"]).gettext - See the python gettext documentation. - Assumes path/filename - path/locale/LANG/LC_MESSAGES/addon.mo. + .. seealso:: the python gettext documentation. + + Assumes path/filename = path/locale/LANG/LC_MESSAGES/addon.mo. """ gramps_translator = self._get_translation() @@ -954,8 +957,9 @@ class Lexeme(_LexemeBaseStr): Created with :meth:`~GrampsTranslations.lexgettext` .. rubric:: Example - Python code: - :: + + Python code:: + _ = lexgettext dec = _("localized lexeme inflections||December") xmas = _("lexeme||Christmas") @@ -965,8 +969,8 @@ class Lexeme(_LexemeBaseStr): XMAS = xmas.upper() print ("\n".join([XMAS, text, greeting])) - Translation database (Russian example): - :: + Translation database (Russian example):: + msgid "lexeme||December" msgstr "NOMINATIVE=декабрь|GENITIVE=декабря|ABLATIVE=декабрём|LOCATIVE=декабре" @@ -979,19 +983,20 @@ class Lexeme(_LexemeBaseStr): msgid "Merry {holiday}!" msgstr "Счастливого {holiday.f[GENITIVE]}!" - Prints out: + Prints out:: + In English locale: - :: CHRISTMAS Christmas is celebrated in December Merry Christmas! + In Russian locale: - :: РОЖДЕСТВО рождество празднуют в декабре Счастливого рождества! .. rubric:: Description + Stores an arbitrary number of forms, e.g., inflections. These forms are accessible under dictionary keys for each form. The names of the forms are language-specific. They are assigned @@ -1013,14 +1018,15 @@ class Lexeme(_LexemeBaseStr): the same nominative form in capital letters. .. rubric:: Motivation + Lexeme is the term used in linguistics for the set of forms taken by a particular word, e.g. cases for a noun or tenses for a verb. Gramps often needs to compose sentences from several blocks of text and single words, often by using python string formatting. - For instance, formatting a date range is done similarly to this: - :: + For instance, formatting a date range is done similarly to this:: + _("Between {startdate_month} {startdate_year}" "and {enddate_month} {enddate_year}").format( startdate_month = m1, diff --git a/gramps/gen/utils/place.py b/gramps/gen/utils/place.py index 50e0411c0..1e6f8ff04 100644 --- a/gramps/gen/utils/place.py +++ b/gramps/gen/utils/place.py @@ -323,30 +323,44 @@ def __convert_float_val(val, typedeg = "lat"): def conv_lat_lon(latitude, longitude, format="D.D4"): """ Convert given string latitude and longitude to a required format. + + :param latitude: Latitude + :type latitude: string + :param longitude: Longitude + :type longitude: string + :param format: Ouput format + :type format: string + :returns: a tuple of 2 strings, or a string (for ISO formats). If + conversion fails: returns: (None, None) or None (for ISO formats) + Possible formats: - 'D.D4' : degree notation, 4 decimals - eg +12.0154 , -124.3647 - 'D.D8' : degree notation, 8 decimals (precision like ISO-DMS) - eg +12.01543265 , -124.36473268 - 'DEG' : degree, minutes, seconds notation - eg 50°52'21.92''N , 124°52'21.92''E ° has UTF-8 code c2b00a - or N50º52'21.92" , E14º52'21.92" º has UTF-8 code c2ba0a - or N50º52.3456' , E14º52.9876' ; decimal minutes, no seconds - 'DEG-:' : degree, minutes, seconds notation with : - eg -50:52:21.92 , 124:52:21.92 - 'ISO-D' : ISO 6709 degree notation i.e. ±DD.DDDD±DDD.DDDD - 'ISO-DM' : ISO 6709 degree, minutes notation - i.e. ±DDMM.MMM±DDDMM.MMM - 'ISO-DMS' : ISO 6709 degree, minutes, seconds notation - i.e. ±DDMMSS.SS±DDDMMSS.SS - 'RT90' : Output format for the Swedish coordinate system RT90 + + ========= ============================================================ + Format Description + ========= ============================================================ + 'D.D4' degree notation, 4 decimals + eg +12.0154 , -124.3647 + 'D.D8' degree notation, 8 decimals (precision like ISO-DMS) + eg +12.01543265 , -124.36473268 + 'DEG' degree, minutes, seconds notation + eg 50°52'21.92''N , 124°52'21.92''E ° has UTF-8 code c2b00a + or N50º52'21.92" , E14º52'21.92" º has UTF-8 code c2ba0a + or N50º52.3456' , E14º52.9876' ; decimal minutes, no seconds + 'DEG-:' degree, minutes, seconds notation with : + eg -50:52:21.92 , 124:52:21.92 + 'ISO-D' ISO 6709 degree notation i.e. ±DD.DDDD±DDD.DDDD + 'ISO-DM' ISO 6709 degree, minutes notation + i.e. ±DDMM.MMM±DDDMM.MMM + 'ISO-DMS' ISO 6709 degree, minutes, seconds notation + i.e. ±DDMMSS.SS±DDDMMSS.SS + 'RT90' Output format for the Swedish coordinate system RT90 + ========= ============================================================ - Return value: a tuple of 2 strings, or a string (for ISO formats) - If conversion fails: returns: (None, None) or None (for ISO formats) Some generalities: - -90 <= latitude <= +90 with +00 the equator - -180 <= longitude < +180 with +000 prime meridian - and -180 180th meridian + + * -90 <= latitude <= +90 with +00 the equator + * -180 <= longitude < +180 with +000 prime meridian and -180 the 180th + meridian """ # we start the function changing latitude/longitude in english