API Documentation

class months.Month(year, month)

Represent a specific month of a year.

Provides various utilities for generating, manipulating, and displaying months.

abbr_display

Return the abbreviated calendar name of the month and the year.

>>> Month(2015, 4).full_display
'Apr 2015'

dates

Return a tuple of all days in the month.

>>> Month(2018, 1).dates[:2]
(datetime.date(2018, 1, 1), datetime.date(2018, 1, 2))

distance(self, *args, **kwargs)

Return the number of months distance between months.

This will always be a positive number. Accepts two-element lists/tuples or Month objects.

>>> Month(2018, 1).distance(Month(2018, 12))
11
>>> Month(2018, 5).distance(2018, 1)
4

Parameters:

other : Month, date, datetime, tuple

A Month-like object.

Returns:

n_months : int

Integer number of months distance.

end_date

Return a datetime.date object for the last day of the month.

classmethod from_date(cls, date)

Return a Month instance from given a date or datetime object.

Parameters:

date : date or datetime

A date/datetime object as implemented via the standard lib module.

Returns:

month : Month

The month object for that date.

classmethod from_today(cls)

Return a Month instance from today’s date (local time).

classmethod from_utc_today(cls)

Return a Month instance from today’s date (UTC time).

full_display

Return the calendar name of the month along with the year.

>>> Month(2015, 4).full_display
'April 2015'

gregorian_month_number

Return the number of months since the start of Gregorian year 1.

Year 0 and month 0 are invalid. So the first month of year 1 is 1, and the first month of year -1 is -1.

>>> Month(1, 1).gregorian_month_number
1
>>> Month(2, 2).gregorian_month_number
14
>>> Month(-1, 2).gregorian_month_number
-2

month_abbr

Return the abbreviated calendar name of the month.

>>> Month(2015, 4).month_abbr
'Apr'

month_name

Return the calendar name of the month.

>>> Month(2015, 4).month_name
'April'

n_days

Return the number of days in the month.

>>> Month(2018, 1).n_days
31

nth(self, day)

Get date object for nth day of month.

Accepts nonzero integer values between +- month.n_days.

>>> Month(2018, 1).nth(1) == Month(2018, 1).start_date
True
>>> Month(2018, 1).nth(8)
datetime.date(2018, 1, 8)

>>> Month(2018, 1).nth(-2)
datetime.date(2018, 1, 30)

Parameters:

day : int

Day of the month.

Returns:

date : datetime.date

Date object for the day of the month.

range

Return a tuple of the first and last days of the month.

start_date

Return a datetime.date object for the first day of the month.

to(self, *args, **kwargs)

Generate a list of all months between two months, inclusively.

Accepts two-element lists/tuples, date-like objects, or Month objects. If months are provided out of order (like june_18.to.march_18) then the list will also be in reverse order.

>>> Month(2018, 1).to(Month(2018, 2))
[Month(2018, 1), Month(2018, 2)]
>>> Month(2018, 3).to(2018, 1)
[Month(2018, 3), Month(2018, 2), Month(2018, 1)]

Parameters:

other : Month, date, datetime, tuple

A Month-like object.

Returns:

months : list

List of months spanning the two objects, inclusively.