https://github.com/python/cpython/commit/e0f0d2d2b899ceec3a7d1853f75dd50efa5... commit: e0f0d2d2b899ceec3a7d1853f75dd50efa5e2f1e branch: 3.13 author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> committer: erlend-aasland <erlend.aasland@protonmail.com> date: 2025-01-03T10:03:45Z summary: [3.13] gh-108202: Document calendar.TextCalendar formatting helpers (GH-127608) (#128440) Document the following TextCalendar methods: - formatday() - formatmonthname() - formatweekday() - formatweekheader() (cherry picked from commit bb73426cafb78691b249ffa50f1872ab6f899d4a) Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> files: M Doc/library/calendar.rst diff --git a/Doc/library/calendar.rst b/Doc/library/calendar.rst index 9a4395ecb5084d..97ca34b6c6184c 100644 --- a/Doc/library/calendar.rst +++ b/Doc/library/calendar.rst @@ -138,6 +138,14 @@ interpreted as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is :class:`TextCalendar` instances have the following methods: + + .. method:: formatday(theday, weekday, width) + + Return a string representing a single day formatted with the given *width*. + If *theday* is ``0``, return a string of spaces of + the specified width, representing an empty day. The *weekday* parameter + is unused. + .. method:: formatweek(theweek, w=0) Return a single week in a string with no newline. If *w* is provided, it @@ -145,6 +153,17 @@ interpreted as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is on the first weekday as specified in the constructor or set by the :meth:`setfirstweekday` method. + .. method:: formatweekday(weekday, width) + + Return a string representing the name of a single weekday formatted to + the specified *width*. The *weekday* parameter is an integer representing + the day of the week, where ``0`` is Monday and ``6`` is Sunday. + + .. method:: formatweekheader(width) + + Return a string containing the header row of weekday names, formatted + with the given *width* for each column. The names depend on the locale + settings and are padded to the specified width. .. method:: formatmonth(theyear, themonth, w=0, l=0) @@ -154,6 +173,12 @@ interpreted as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is on the first weekday as specified in the constructor or set by the :meth:`setfirstweekday` method. + .. method:: formatmonthname(theyear, themonth, width=0, withyear=True) + + Return a string representing the month's name centered within the + specified *width*. If *withyear* is ``True``, include the year in the + output. The *theyear* and *themonth* parameters specify the year + and month for the name to be formatted respectively. .. method:: prmonth(theyear, themonth, w=0, l=0) @@ -445,7 +470,7 @@ The :mod:`calendar` module exports the following data attributes: A sequence that represents the months of the year in the current locale. This follows normal convention of January being month number 1, so it has a length of - 13 and ``month_name[0]`` is the empty string. + 13 and ``month_name[0]`` is the empty string. >>> import calendar >>> list(calendar.month_name)