A fiscal helper for retail calendars
Project description
The Fiscal Calendar Helper is a set of fiscal calendar helper functions that enables easy use and navigation of a fiscal calendar in Python 3 projects.
API Reference:
- Installation
- The Fiscal Calendar
- Time Offsets - Moving between time periods
- Time Conversions - Converting between time levels
- Parent / Child Time Relationships - Managing time in with the hierarchy
- More Info - Repo, bugs, license info
Installation
To use the fiscal helper:
from fiscal_calendar_helper import fiscal
The Fiscal Calendar
The current fiscal calendar is based on the National Retail Federation's 4-5-4 calendar. In the future, we plan to support other calendars (Gregorian), different starting days of week, and longer time horizons.
The current supported years are 2016 - 2025
Time Levels
Our fiscal calendar is capable of supportting different levels of the calendar hierarchy. While many of the examples may look similar to the other levels, their structures are not interchangable and mean something specific to that level.
Level | Description | Example | Data Type | Relative or Absolute |
---|---|---|---|---|
key |
This is a numeric key for this record and should not be confused with the date itself. This is most likely not what you're looking for. It's a structure holding counts of year, week, and day_of_week as an index starting at 1. For example this key 2023_07_7 actually represents the date 3/18/23 which looks totally different. |
2023_07_7 |
string |
Absolute |
week_id |
This is unique id for this fiscal week | 2023_07 |
string |
Absolute |
year |
This is the fiscal year. | 2023 |
string |
Absolute |
quarter |
This is the fiscal quarter. | Q1 |
string |
Relative |
month |
This is the fiscal month. | March |
string |
Relative |
week_num |
This is a relative count of the number of weeks in the year. | 7 |
string |
Relative |
day_of_week |
This is the day of the week in plain text. | Saturday |
string |
Absolute |
date |
This is a datetime formatted representation of the fiscal date. | 2023-03-18 |
datetime |
Absolute |
date_id |
This is the id for this date. | 2023_03_18 |
string |
Absolute |
Relative vs Absolute Levels
Absolute levels mean that this column only uses one value for a specific time period, where as relative levels mean that the value in the column may be repeated over several time periods.
A week_id
such as 2023_07
is absolute because it will only occur once on the calendar, where as week_num
such as 7
because that will exist for every year in the calendar.
Most of the time, you'll likely be working with absolute dates only - like finding the starting date for a particular week. But you may also want to compare months (Relative) across several years (Absolute) to create a table where values can be compared directly.
fiscal.calendar
The actual fiscal calendar is stored as a pandas table located at fiscal.calendar
.
Time Offsets
All of the time offsets are currently only built to work with week_id
or date_id
levels.
fiscal.offset()
offset(input, offset)
Returns week_id
or date_id
offset by specified periods.
>>> fiscal.offset('2022_31', 4)
'2022_35'
fiscal.next()
next(input)
Returns the next week or date.
>>> fiscal.next('2022_31')
'2022_32'
fiscal.previous()
previous(input)
Returns the previous week or date.
>>> fiscal.previous('2022_31')
'2022_30'
Time Conversions
Time conversions allow for easy translation between years, weeks, week nums, etc without having to parse strings.
fiscal.convert()
fiscal.convert(input, inp_level, out_level)
The convert
function takes an input and level type, and output level and converts the value. If there are multiple valid answers, it will return the first time in the list.
Example: Find the starting date for a fiscal week
>>> fiscal.convert('2022_36', 'week_id', 'date')
['2016_02_14', '2016_02_15', '2016_02_16', '2016_02_17']
Parent / Child Time Relationships
Time is structured into a hierarchy, which means that there are parent and child elements in the hierarchy structure. You can read more on parent-child hierarchies if the concept is unfamiliar.
For our purposes a parent-like level will be any level that contains multiple child elements of the same type.
Examples:
year
is parent-like toquarter
week
is child-like toquarter
week
is parent-like todate
anddate_id
year
is parent-like todate
date
is child-like tomonth
fiscal.fill_to()
fill_to(input, child_level = 'date_id', parent_level = 'week_id', direction = 'start')
The fill_to
function takes a child input as a starting point, and then a parent output as a container, and lists the remaining children in that parent.
Example: Given a date, find the remaining dates in the week.
>>> fiscal.fill_to('2016_02_18', 'date_id', 'week_id', 'start')
['2016_02_14', '2016_02_15', '2016_02_16', '2016_02_17']
fiscal.unpack()
unpack(input, parent_level, child_level)
The unpack
function takes in a parent level and returns all the children contained withint it.
Example: Return all dates within a quarter.
>>> fiscal.unpack('2016_01', 'week_id', 'date_id')
['2016_02_07', '2016_02_08', '2016_02_09', '2016_02_10', '2016_02_11', '2016_02_12', '2016_02_13']
More info
- Author: Phillip Geltman
- License Type: MIT License
- Github Repo: https://github.com/Growthsayer/fiscal-helper
- Bug Tracker: https://github.com/Growthsayer/fiscal-helper/issues
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for fiscal_calendar_helper-1.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 513148277faac68cef9aa5710d99cb0b919cf3745b981b3b5c2f8bd205cd488c |
|
MD5 | efc663c34d67aac1bb6fa1d9abf75b2d |
|
BLAKE2b-256 | d1892b2f32d5ce4b070edc2d2209034eb1a042dd945cf889cd3d39e1646cb065 |
Hashes for fiscal_calendar_helper-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 68921f4b6836d24b4a7df653e4756dd82f8392d449a3a57e7bb14e75ec2ecfc4 |
|
MD5 | 515805745afadb3410e33cb8db8ef4e8 |
|
BLAKE2b-256 | 89278fdab56971bf1f8dbac9d5ea5122102124758e47f07489fd77c0a789aa6b |