Improve date handler documentation
This commit is contained in:
Nick Hall
parent
55a3c9813f
commit
19b39b5dc0
@ -82,14 +82,12 @@ class DateDisplay(object):
|
||||
_("DAY MON YEAR")
|
||||
)
|
||||
"""
|
||||
:Note:
|
||||
Will be overridden if a locale-specific date displayer exists.
|
||||
.. note:: Will be overridden if a locale-specific date displayer exists.
|
||||
|
||||
If your localized ``_display_gregorian`` / ``_display_calendar`` are overridden,
|
||||
you should override the whole formats list according to your own formats,
|
||||
and you need not localize the format names here.
|
||||
this ``formats`` must agree with
|
||||
:meth:`~_display_calendar`/:meth:`~_display_gregorian`
|
||||
If your localized :meth:`~_display_calendar`/:meth:`~_display_gregorian` are
|
||||
overridden,you should override the whole formats list according to your own
|
||||
formats, and you need not localize the format names here. This ``formats``
|
||||
must agree with :meth:`~_display_calendar`/:meth:`~_display_gregorian`.
|
||||
"""
|
||||
del _
|
||||
|
||||
|
||||
@ -101,16 +101,16 @@ def register_datehandler(locales,parse_class,display_class):
|
||||
classes with the specified language locales.
|
||||
|
||||
Set the parser_class and display_class ._locale attribute
|
||||
to the corresponding GrampsLocale object.
|
||||
to the corresponding :class:`.GrampsLocale` object.
|
||||
|
||||
@param locales: tuple of strings containing language codes.
|
||||
The character encoding is not included, so the language
|
||||
should be in the form of fr_FR, not fr_FR.utf8
|
||||
@type locales: tuple
|
||||
@param parse_class: Class to be associated with parsing
|
||||
@type parse_class: DateParse
|
||||
@param display_class: Class to be associated with displaying
|
||||
@type display_class: DateDisplay
|
||||
:param locales: tuple of strings containing language codes.
|
||||
The character encoding is not included, so the language
|
||||
should be in the form of fr_FR, not fr_FR.utf8
|
||||
:type locales: tuple
|
||||
:param parse_class: Class to be associated with parsing
|
||||
:type parse_class: :class:`.DateParser`
|
||||
:param display_class: Class to be associated with displaying
|
||||
:type display_class: :class:`.DateDisplay`
|
||||
"""
|
||||
for lang_str in locales:
|
||||
LANG_TO_PARSER[lang_str] = parse_class
|
||||
|
||||
@ -158,18 +158,17 @@ def _build_prefix_table(month_to_int, month_variants):
|
||||
def _generate_variants(months):
|
||||
"""
|
||||
Generate all month variants for passing to _build_prefix_table
|
||||
@param months an iterable ordered collection,
|
||||
1st item is empty, the rest 1..N, for a
|
||||
calendar with N months overall, contain, each,
|
||||
an iterable of alternative specifications.
|
||||
Each such specification can be:
|
||||
1) a Lexeme, supporting .variants()
|
||||
to return the list of variants underneath
|
||||
2) a literal string
|
||||
3) a |-separated string of alternatives
|
||||
Empty strings are discarded.
|
||||
@return generator of lists per month with all variants listed once only
|
||||
the 1st item will be empty
|
||||
:param months: an iterable ordered collection, 1st item is empty, the rest
|
||||
1..N, for a calendar with N months overall, contain, each,
|
||||
an iterable of alternative specifications.
|
||||
Each such specification can be:
|
||||
1) a Lexeme, supporting .variants() to return the list of
|
||||
variants underneath
|
||||
2) a literal string
|
||||
3) a |-separated string of alternatives
|
||||
Empty strings are discarded.
|
||||
:return: generator of lists per month with all variants listed once only
|
||||
the 1st item will be empty
|
||||
"""
|
||||
|
||||
for month_lexemes_and_alternatives in months:
|
||||
@ -193,7 +192,7 @@ def _generate_variants(months):
|
||||
#-------------------------------------------------------------------------
|
||||
class DateParser(object):
|
||||
"""
|
||||
Convert a text string into a Date object. If the date cannot be
|
||||
Convert a text string into a :class:`.Date` object. If the date cannot be
|
||||
converted, the text string is assigned.
|
||||
"""
|
||||
|
||||
@ -377,7 +376,9 @@ class DateParser(object):
|
||||
may be called first as DateParser.init_strings(self) so that the
|
||||
invariant expresions don't need to be repeteadly coded. All differences
|
||||
can be coded after DateParser.init_strings(self) call, that way they
|
||||
override stuff from this method. See DateParserRU() as an example.
|
||||
override stuff from this method.
|
||||
|
||||
.. seealso:: :class:`.DateParserRU` as an example.
|
||||
"""
|
||||
_ = self._locale.translation.gettext
|
||||
self.__init_prefix_tables()
|
||||
@ -876,7 +877,7 @@ class DateParser(object):
|
||||
|
||||
def parse(self, text):
|
||||
"""
|
||||
Parses the text, returning a Date object.
|
||||
Parses the text, returning a :class:`.Date` object.
|
||||
"""
|
||||
new_date = Date()
|
||||
try:
|
||||
|
||||
@ -40,7 +40,7 @@ log = logging.getLogger(".DateStrings")
|
||||
#-------------------------------------------------------------------------
|
||||
class DateStrings(object):
|
||||
"""
|
||||
String tables for :class:`~DateDisplay` and :class:`~DateParser`.
|
||||
String tables for :class:`.DateDisplay` and :class:`.DateParser`.
|
||||
"""
|
||||
|
||||
# This table needs not be localized, it's only for parsing
|
||||
@ -233,16 +233,17 @@ __doc__ += """
|
||||
__main__
|
||||
--------
|
||||
|
||||
Run this code with the appropriate ``LANG`` and ``LC_DATE`` set for your target language,
|
||||
in order to generate the .po snippets initialized with the strings from your locale
|
||||
(from the deprecated data provided in _grampslocale).
|
||||
Run this code with the appropriate ``LANG`` and ``LC_DATE`` set for your target
|
||||
language, in order to generate the .po snippets initialized with the strings
|
||||
from your locale (from the deprecated data provided in _grampslocale).
|
||||
|
||||
E.g., for French::
|
||||
|
||||
E.g., for French:
|
||||
::
|
||||
LANG=fr_FR.utf8 LC_ALL=fr_FR.utf8 GRAMPS_RESOURCES=$PWD python -m gramps.gen.datehandler._datestrings
|
||||
|
||||
Then merge the output into your language's .po file, and further modify the strings as needed.
|
||||
Then remove the strings from your language's ``DateParserXX`` and ``DateHandlerXX`` classes.
|
||||
Then merge the output into your language's .po file, and further modify the
|
||||
strings as needed. Then remove the strings from your language's
|
||||
:class:`DateParserXX` and :class:`DateHandlerXX` classes.
|
||||
"""
|
||||
|
||||
if __name__ == '__main__':
|
||||
|
||||
@ -61,27 +61,27 @@ def set_format(value):
|
||||
|
||||
def set_date(date_base, text) :
|
||||
"""
|
||||
Set the date of the DateBase instance.
|
||||
Set the date of the :class:`.DateBase` instance.
|
||||
|
||||
The date is parsed into a Date instance.
|
||||
|
||||
@param date_base: The DateBase instance to set the date to.
|
||||
@type date_base: DateBase
|
||||
@param text: The text to use for the text string in date
|
||||
@type text: str
|
||||
The date is parsed into a :class:`.Date` instance.
|
||||
|
||||
:param date_base: The :class:`.DateBase` instance to set the date to.
|
||||
:type date_base: :class:`.DateBase`
|
||||
:param text: The text to use for the text string in date
|
||||
:type text: str
|
||||
"""
|
||||
parser.set_date(date_base.get_date_object(), text)
|
||||
|
||||
def get_date(date_base) :
|
||||
"""
|
||||
Return a string representation of the date of the DateBase instance.
|
||||
Return a string representation of the date of the :class:`.DateBase`
|
||||
instance.
|
||||
|
||||
This representation is based off the default date display format
|
||||
determined by the locale's DateDisplay instance.
|
||||
@return: Returns a string representing the DateBase date
|
||||
@rtype: str
|
||||
determined by the locale's :class:`.DateDisplay` instance.
|
||||
|
||||
:return: Returns a string representing the :class:`.DateBase` date
|
||||
:rtype: str
|
||||
"""
|
||||
return displayer.display(date_base.get_date_object())
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user