beansoup.utils package

Submodules

beansoup.utils.dates module

Utilities for working with dates.

beansoup.utils.dates.MONTHS

Dict[str, int]

a map from month names to their ordinal values, starting at 1. The names are lowercase and can be full names, three-letter abbreviations, or one- or two-digit representations.

beansoup.utils.dates.add_biz_days(date, num_biz_days)[source]

Add a number of business days to a date.

If the starting date falls on a weekend, it is moved to the next business day before adding the delta.

Parameters:
  • date (datetime.date) – The starting date.
  • num_biz_days (int) – The number of business days to add to the starting date; it must be non-negative.
Returns:

the offset date.
Return type:

datetime.date
beansoup.utils.dates.month_number(month)[source]

Turns a month name into its corresponding month number.

It recognizes full and abbreviated (three letters) English month names (case insensitive) as well as month number with or without a leading 0.

Parameters:month (str) – The name of a month or its three-letter abbreviation or its numerical equivalent.
Returns:The number in [1,12] corresponding to the given month name, or None if it does not recognize the given name.
Return type:Optional[int]

beansoup.utils.periods module

Utilities to work with monthly billing periods.

beansoup.utils.periods.count(date, reverse=False)[source]

A generator of monthly-spaced dates.

It enumerates monthly-spaced dates, starting at the given date. If the starting date falls on a day that is not in a given month, the date for that month will be the last day of that month.

Parameters:
  • date (datetime.date) – The starting date.
  • reverse (bool) – If True, it generates dates in reverse chronological order.
Yields:

datetime.date – the next date in the sequence.

Example

>>> import datetime
>>> import itertools
>>> start = datetime.date(2016, 1, 31)
>>> [date.isoformat() for date in itertools.islice(count(start), 5)]
['2016-01-31', '2016-02-29', '2016-03-31', '2016-04-30', '2016-05-31']
beansoup.utils.periods.enclose_date(date, first_day=1)[source]

Compute the monthly period containing the given date.

Parameters:
  • date (datetime.date) – The date to be contained.
  • first_day (int) – The first day of the monthly cycle. It must fall in the interval [1,28].
Returns:

The start and end dates (inclusives) of the monthly period containing the given date.
Return type:

Tuple[datetime.date, datetime.date]
beansoup.utils.periods.greatest_start(date, first_day=1)[source]

Compute the starting date of the monthly period containing the given date.

More formally, given a monthly cycle starting on first_day day of the month, it computes the greatest starting date that is less than or equal to the given date.

Parameters:
  • date (datetime.date) – An arbitrary date.
  • first_day (int) – The first day of the monthly cycle. It must fall in the interval [1,28].
Returns:

The starting date of the monthly period containing the given date.
Return type:

datetime.date
beansoup.utils.periods.lowest_end(date, first_day=1)[source]

Compute the ending date of the monthly period containing the given date.

More formally, given a monthly cycle starting on first_day day of the month, it computes the lowest ending date that is greater than or equal to the given date. Note that the ending date is inclusive, i.e. it is included in the monthly period.

Parameters:
  • date (datetime.date) – An arbitrary date.
  • first_day (int) – The first day of the monthly cycle. It must fall in the interval [1,28].
Returns:

The ending date of the monthly period containing the given date.
Return type:

datetime.date
beansoup.utils.periods.next(date)[source]

Add one month to the given date.

Parameters:date (datetime.date) – The starting date.
Returns:One month after the starting date unless the starting date falls on a day that is not in the next month; in that case, it returns the last day of the next month.
Return type:datetime.date

Example

>>> import datetime
>>> next(datetime.date(2016, 1, 31))
datetime.date(2016, 2, 29)
beansoup.utils.periods.prev(date)[source]

Subtract one month from the given date.

Parameters:date (datetime.date) – The starting date.
Returns:One month before the starting date unless the starting date falls on a day that is not in the previous month; in that case, it returns the last day of the previous month.
Return type:datetime.date

Example

>>> import datetime
>>> prev(datetime.date(2016, 3, 31))
datetime.date(2016, 2, 29)

Module contents