Python's calendar.month in TypeScript

How to use

Install via yarn add locutus and import: import { month } from 'locutus/python/calendar/month'.

Or with CommonJS: const { month } = require('locutus/python/calendar/month')

Use a bundler that supports tree-shaking so you only ship the functions you actually use. Vite, webpack, Rollup, and Parcel all handle this. For server-side use this is less of a concern.

Examples

These examples are extracted from test cases that automatically verify our functions against their native counterparts.

#	code	expected result
1	month(2024, 2)	' February 2024\nMo Tu We Th Fr Sa Su\n 1 2 3 4\n 5 6 7 8 9 10 11\n12 13 14 15 16 17 18\n19 20 21 22 23 24 25\n26 27 28 29\n'

Dependencies

This function uses the following Locutus functions:

• _calendar (python/_helpers)

Here's what our current TypeScript equivalent to Python's calendar.month looks like.

TSTypeScript JSJavaScript TSStandalone TS JSStandalone JS

Copy code

import {
  formatMonth,
  normalizeCalendarMonth,
  normalizeCalendarYear,
  normalizeLineSpacing,
  normalizeMonthWidth,
} from '../_helpers/_calendar.ts'

export function month(theyear: unknown, themonth: unknown, w = 0, l = 0): string {
  //      discuss at: https://locutus.io/python/calendar/month/
  // parity verified: Python 3.12
  //     original by: Kevin van Zonneveld (https://kvz.io)
  //       example 1: month(2024, 2)
  //       returns 1: '   February 2024\nMo Tu We Th Fr Sa Su\n          1  2  3  4\n 5  6  7  8  9 10 11\n12 13 14 15 16 17 18\n19 20 21 22 23 24 25\n26 27 28 29\n'

  if (arguments.length === 0) {
    throw new TypeError("TextCalendar.formatmonth() missing 2 required positional arguments: 'theyear' and 'themonth'")
  }
  if (arguments.length === 1) {
    throw new TypeError("TextCalendar.formatmonth() missing 1 required positional argument: 'themonth'")
  }

  return formatMonth(
    normalizeCalendarYear(theyear, 'month'),
    normalizeCalendarMonth(themonth, 'month'),
    normalizeMonthWidth(w, 'month'),
    normalizeLineSpacing(l, 'month'),
  )
}

import {
  formatMonth,
  normalizeCalendarMonth,
  normalizeCalendarYear,
  normalizeLineSpacing,
  normalizeMonthWidth,
} from '../_helpers/_calendar.ts'

export function month(theyear, themonth, w = 0, l = 0) {
  //      discuss at: https://locutus.io/python/calendar/month/
  // parity verified: Python 3.12
  //     original by: Kevin van Zonneveld (https://kvz.io)
  //       example 1: month(2024, 2)
  //       returns 1: '   February 2024\nMo Tu We Th Fr Sa Su\n          1  2  3  4\n 5  6  7  8  9 10 11\n12 13 14 15 16 17 18\n19 20 21 22 23 24 25\n26 27 28 29\n'

  if (arguments.length === 0) {
    throw new TypeError("TextCalendar.formatmonth() missing 2 required positional arguments: 'theyear' and 'themonth'")
  }
  if (arguments.length === 1) {
    throw new TypeError("TextCalendar.formatmonth() missing 1 required positional argument: 'themonth'")
  }

  return formatMonth(
    normalizeCalendarYear(theyear, 'month'),
    normalizeCalendarMonth(themonth, 'month'),
    normalizeMonthWidth(w, 'month'),
    normalizeLineSpacing(l, 'month'),
  )
}

// python/_helpers/_calendar (Locutus helper dependency)
const DAY_ABBR = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] as const

const MONTH_NAMES = [
  '',
  'January',
  'February',
  'March',
  'April',
  'May',
  'June',
  'July',
  'August',
  'September',
  'October',
  'November',
  'December',
] as const

function toCalendarInteger(value: unknown, functionName: string): number {
  if (typeof value === 'boolean') {
    return value ? 1 : 0
  }

  if (typeof value === 'bigint') {
    const numericValue = Number(value)
    if (!Number.isSafeInteger(numericValue)) {
      throw new RangeError(`${functionName}() integer arguments must fit within JS safe integer precision`)
    }

    return numericValue
  }

  if (typeof value === 'number' && Number.isFinite(value) && Number.isSafeInteger(value)) {
    return value
  }

  throw new TypeError(`${functionName}() requires integer arguments`)
}

function normalizeCalendarYear(value: unknown, functionName: string): number {
  return toCalendarInteger(value, functionName)
}

function normalizeCalendarMonth(value: unknown, functionName: string): number {
  const month = toCalendarInteger(value, functionName)
  if (month < 1 || month > 12) {
    throw new RangeError('bad month number')
  }

  return month
}

function normalizeMonthWidth(value: unknown, functionName: string): number {
  return Math.max(toCalendarInteger(value, functionName), 2)
}

function normalizeLineSpacing(value: unknown, functionName: string): number {
  return Math.max(toCalendarInteger(value, functionName), 1)
}

function isLeapYear(year: number): boolean {
  return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0)
}

function daysInMonth(year: number, month: number): number {
  if (month === 2) {
    return isLeapYear(year) ? 29 : 28
  }

  return [4, 6, 9, 11].includes(month) ? 30 : 31
}

function pythonWeekday(year: number, month: number, day: number): number {
  const ordinal = daysBeforeYear(year) + daysBeforeMonth(year, month) + day
  return positiveModulo(ordinal - 1, 7)
}

function buildWeekHeader(width: number): string {
  return DAY_ABBR.map((name) => {
    const truncated = name.slice(0, width)
    return width > truncated.length ? centerText(truncated, width) : truncated
  }).join(' ')
}

function buildMonthCalendar(year: number, month: number): number[][] {
  const totalDays = daysInMonth(year, month)
  const firstWeekday = pythonWeekday(year, month, 1)
  const weeks: number[][] = []

  let currentWeek = new Array<number>(7).fill(0)
  let weekdayIndex = firstWeekday

  for (let day = 1; day <= totalDays; day += 1) {
    currentWeek[weekdayIndex] = day
    weekdayIndex += 1

    if (weekdayIndex === 7) {
      weeks.push(currentWeek)
      currentWeek = new Array<number>(7).fill(0)
      weekdayIndex = 0
    }
  }

  if (weekdayIndex !== 0) {
    weeks.push(currentWeek)
  }

  return weeks
}

function formatWeek(theweek: unknown, width: unknown): string {
  if (!Array.isArray(theweek)) {
    throw new TypeError("'int' object is not iterable")
  }

  const rawWidth = toCalendarInteger(width, 'week')
  return theweek
    .map((entry) => {
      if (!Array.isArray(entry)) {
        throw new TypeError("'int' object is not iterable")
      }

      const day = entry[0]
      if (typeof day !== 'number' || !Number.isInteger(day)) {
        throw new TypeError("'int' object is not iterable")
      }

      if (day === 0) {
        return centerText('', rawWidth)
      }

      return centerText(String(day).padStart(2, ' '), rawWidth)
    })
    .join(' ')
}

function formatMonth(year: number, month: number, width: number, lineSpacing: number): string {
  const monthWidth = 7 * (width + 1) - 1
  const header = centerText(`${MONTH_NAMES[month]} ${year}`, monthWidth)
  const weekHeader = buildWeekHeader(width)
  const weeks = formatMonthWeeks(year, month, width)

  return joinCalendarLines([header, weekHeader, ...weeks], lineSpacing)
}

function daysBeforeYear(year: number): number {
  const adjusted = year - 1
  return adjusted * 365 + Math.floor(adjusted / 4) - Math.floor(adjusted / 100) + Math.floor(adjusted / 400)
}

function daysBeforeMonth(year: number, month: number): number {
  const offsets = isLeapYear(year)
    ? [0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335]
    : [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334]
  return offsets[month - 1] ?? 0
}

function centerText(value: string, width: number): string {
  if (width <= value.length) {
    return value
  }

  const leftPadding = Math.floor((width - value.length) / 2)
  const rightPadding = width - value.length - leftPadding
  return `${' '.repeat(leftPadding)}${value}${' '.repeat(rightPadding)}`
}

function positiveModulo(value: number, modulus: number): number {
  return ((value % modulus) + modulus) % modulus
}

function joinCalendarLines(lines: string[], lineSpacing: number): string {
  return `${lines.map((line) => line.replace(/\s+$/, '')).join('\n'.repeat(lineSpacing))}\n`
}

function formatMonthWeeks(year: number, month: number, width: number): string[] {
  return buildMonthCalendar(year, month).map((week) =>
    formatWeek(
      week.map((day, weekday) => [day, weekday]),
      width,
    ),
  )
}

// python/calendar/month (target function module)
function month(theyear: unknown, themonth: unknown, w = 0, l = 0): string {
  //      discuss at: https://locutus.io/python/calendar/month/
  // parity verified: Python 3.12
  //     original by: Kevin van Zonneveld (https://kvz.io)
  //       example 1: month(2024, 2)
  //       returns 1: '   February 2024\nMo Tu We Th Fr Sa Su\n          1  2  3  4\n 5  6  7  8  9 10 11\n12 13 14 15 16 17 18\n19 20 21 22 23 24 25\n26 27 28 29\n'

  if (arguments.length === 0) {
    throw new TypeError("TextCalendar.formatmonth() missing 2 required positional arguments: 'theyear' and 'themonth'")
  }
  if (arguments.length === 1) {
    throw new TypeError("TextCalendar.formatmonth() missing 1 required positional argument: 'themonth'")
  }

  return formatMonth(
    normalizeCalendarYear(theyear, 'month'),
    normalizeCalendarMonth(themonth, 'month'),
    normalizeMonthWidth(w, 'month'),
    normalizeLineSpacing(l, 'month'),
  )
}

// python/_helpers/_calendar (Locutus helper dependency)
const DAY_ABBR = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']

const MONTH_NAMES = [
  '',
  'January',
  'February',
  'March',
  'April',
  'May',
  'June',
  'July',
  'August',
  'September',
  'October',
  'November',
  'December',
]

function toCalendarInteger(value, functionName) {
  if (typeof value === 'boolean') {
    return value ? 1 : 0
  }

  if (typeof value === 'bigint') {
    const numericValue = Number(value)
    if (!Number.isSafeInteger(numericValue)) {
      throw new RangeError(`${functionName}() integer arguments must fit within JS safe integer precision`)
    }

    return numericValue
  }

  if (typeof value === 'number' && Number.isFinite(value) && Number.isSafeInteger(value)) {
    return value
  }

  throw new TypeError(`${functionName}() requires integer arguments`)
}

function normalizeCalendarMonth(value, functionName) {
  const month = toCalendarInteger(value, functionName)
  if (month < 1 || month > 12) {
    throw new RangeError('bad month number')
  }

  return month
}

function normalizeMonthWidth(value, functionName) {
  return Math.max(toCalendarInteger(value, functionName), 2)
}

function normalizeLineSpacing(value, functionName) {
  return Math.max(toCalendarInteger(value, functionName), 1)
}

function isLeapYear(year) {
  return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0)
}

function daysInMonth(year, month) {
  if (month === 2) {
    return isLeapYear(year) ? 29 : 28
  }

  return [4, 6, 9, 11].includes(month) ? 30 : 31
}

function pythonWeekday(year, month, day) {
  const ordinal = daysBeforeYear(year) + daysBeforeMonth(year, month) + day
  return positiveModulo(ordinal - 1, 7)
}

function buildWeekHeader(width) {
  return DAY_ABBR.map((name) => {
    const truncated = name.slice(0, width)
    return width > truncated.length ? centerText(truncated, width) : truncated
  }).join(' ')
}

function buildMonthCalendar(year, month) {
  const totalDays = daysInMonth(year, month)
  const firstWeekday = pythonWeekday(year, month, 1)
  const weeks = []

  let currentWeek = new Array(7).fill(0)
  let weekdayIndex = firstWeekday

  for (let day = 1; day <= totalDays; day += 1) {
    currentWeek[weekdayIndex] = day
    weekdayIndex += 1

    if (weekdayIndex === 7) {
      weeks.push(currentWeek)
      currentWeek = new Array(7).fill(0)
      weekdayIndex = 0
    }
  }

  if (weekdayIndex !== 0) {
    weeks.push(currentWeek)
  }

  return weeks
}

function formatWeek(theweek, width) {
  if (!Array.isArray(theweek)) {
    throw new TypeError("'int' object is not iterable")
  }

  const rawWidth = toCalendarInteger(width, 'week')
  return theweek
    .map((entry) => {
      if (!Array.isArray(entry)) {
        throw new TypeError("'int' object is not iterable")
      }

      const day = entry[0]
      if (typeof day !== 'number' || !Number.isInteger(day)) {
        throw new TypeError("'int' object is not iterable")
      }

      if (day === 0) {
        return centerText('', rawWidth)
      }

      return centerText(String(day).padStart(2, ' '), rawWidth)
    })
    .join(' ')
}

function formatMonth(year, month, width, lineSpacing) {
  const monthWidth = 7 * (width + 1) - 1
  const header = centerText(`${MONTH_NAMES[month]} ${year}`, monthWidth)
  const weekHeader = buildWeekHeader(width)
  const weeks = formatMonthWeeks(year, month, width)

  return joinCalendarLines([header, weekHeader, ...weeks], lineSpacing)
}

function daysBeforeYear(year) {
  const adjusted = year - 1
  return adjusted * 365 + Math.floor(adjusted / 4) - Math.floor(adjusted / 100) + Math.floor(adjusted / 400)
}

function daysBeforeMonth(year, month) {
  const offsets = isLeapYear(year)
    ? [0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335]
    : [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334]
  return offsets[month - 1] ?? 0
}

function centerText(value, width) {
  if (width <= value.length) {
    return value
  }

  const leftPadding = Math.floor((width - value.length) / 2)
  const rightPadding = width - value.length - leftPadding
  return `${' '.repeat(leftPadding)}${value}${' '.repeat(rightPadding)}`
}

function positiveModulo(value, modulus) {
  return ((value % modulus) + modulus) % modulus
}

function joinCalendarLines(lines, lineSpacing) {
  return `${lines.map((line) => line.replace(/\s+$/, '')).join('\n'.repeat(lineSpacing))}\n`
}

function formatMonthWeeks(year, month, width) {
  return buildMonthCalendar(year, month).map((week) =>
    formatWeek(
      week.map((day, weekday) => [day, weekday]),
      width,
    ),
  )
}

const normalizeCalendarYear = toCalendarInteger

// python/calendar/month (target function module)
function month(theyear, themonth, w = 0, l = 0) {
  //      discuss at: https://locutus.io/python/calendar/month/
  // parity verified: Python 3.12
  //     original by: Kevin van Zonneveld (https://kvz.io)
  //       example 1: month(2024, 2)
  //       returns 1: '   February 2024\nMo Tu We Th Fr Sa Su\n          1  2  3  4\n 5  6  7  8  9 10 11\n12 13 14 15 16 17 18\n19 20 21 22 23 24 25\n26 27 28 29\n'

  if (arguments.length === 0) {
    throw new TypeError("TextCalendar.formatmonth() missing 2 required positional arguments: 'theyear' and 'themonth'")
  }
  if (arguments.length === 1) {
    throw new TypeError("TextCalendar.formatmonth() missing 1 required positional argument: 'themonth'")
  }

  return formatMonth(
    normalizeCalendarYear(theyear, 'month'),
    normalizeCalendarMonth(themonth, 'month'),
    normalizeMonthWidth(w, 'month'),
    normalizeLineSpacing(l, 'month'),
  )
}

Improve this function

Locutus is a community effort following The McDonald's Theory: we ship first iterations, hoping others will improve them. If you see something that could be better, we'd love your contribution.

View on GitHub · Edit on GitHub · View Raw

---

Help us add more

Got a rainy Sunday afternoon and a taste for a porting puzzle?

• Get inspiration from the Python 3 standard library string page.
• Click "New file" in the appropriate folder on GitHub. This will fork the project to your account, directly add the file to it, and send a Pull Request to us.

We will then review it. If it's useful to the project and in line with our contributing guidelines your work will become part of Locutus and you'll be automatically credited in the authors section accordingly.

« More Python calendar functions

Star