Metadata-Version: 2.4
Name: fiscal445
Version: 1.1.0
Summary: 445 Fiscal calendar
Author-email: Dv8edRoute <dv8edroute@protonmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dv8edroute/fiscal445
Keywords: fiscal,calendar,445,finance,reporting
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.23
Dynamic: license-file


# fiscal445

## Description

This script was developed to simplify the determination of reporting dates when using a 445 financial calendar. Many companies use the 445 calendar for financial reporting and it is difficult when setting up reports for YTD, MTD, by quarter runs while only relying on a standard calendar. This module simplifies this by allowing you to set your own  start of the year date and weekending day.

## Prerequisites
Built and tested using

python 3.6+, 
pandas 0.25.3+, 
numpy 1.18.0, 
datetime,
sys,

## Deployment
General Deployment


python -m pip install fiscal445



## Usage

### Import the module

```python
import fiscal445 as fc5
```

#### Set the modules parameters.

To initialize the 445 calendar table

Syntax: `fc5.cal = fc5.Calendar('YYYY-MM-DD','day').build()` where the date is the start of your fiscal 445 year and the day arg is the the last day of your fiscal week.

#### Examples:

```python
fc5.cal = fc5.Calendar('2020-02-02','sat').build()
```

### Optional: capturing calendar-boundary days (`capture_outliers`)

Some companies publish their 445 calendar so that it doesn't quite cover
every day of the calendar year — typically 1-6 days at the very start
or end of the year fall outside any fiscal week entirely. That's fine
as long as your underlying sales/transaction data respects the same
boundary. In practice it often doesn't: the source data covers every
calendar day (365/366), but the *reporting* structure is strictly 445,
so those few boundary days become orphaned — present in the data, but
outside any week the calendar recognizes, and easy to miss unless
someone remembers to pull them separately by hand.

`capture_outliers` fixes this by folding those boundary days into week 1
(at the start of the year) and week 52 (at the end), so the calendar
covers every calendar day of the year with no gaps — while leaving
every other week-ending date completely unchanged.

Syntax: `fc5.cal = fc5.Calendar('YYYY-MM-DD','day',capture_outliers=True).build()`

It defaults to `False`, so any existing code that doesn't pass this
argument behaves exactly as it always has.

#### Example

```python
# 2016's fiscal year begins Saturday, Jan 2 -- meaning Friday, Jan 1
# would otherwise be excluded from every week.
fc5.cal = fc5.Calendar('2016-01-02', 'fri', capture_outliers=True).build()
```

Without `capture_outliers`, any query built on this calendar — a week
range, a quarter range, year to date — can never reach Jan 1, 2016;
that date simply doesn't exist anywhere in the table. With it enabled,
week 1 now correctly spans Jan 1 through Jan 8. The same logic applies
symmetrically at the other end of the year, if the last week falls
short of Dec 31.

```python
fc5.cal.show.quarter_dates(1)
```

Without `capture_outliers`: `('2016-01-02', '2016-04-01')`  
With `capture_outliers`: `('2016-01-01', '2016-04-01')`

<br>

<br>

Week of the month it is based on 445 fiscal calendar

```python
fc5.cal.show.cur_week_of_month()
```
returns `1` based on example date

<br>

```python
fc5.cal.show.prior_week_of_month()
```
returns `5` based on example date

<br>

Week of the year it is based on 445

```python
fc5.cal.show.cur_week_of_year()
```
returns `5` 

<br>

Which month of the year it is based on 445 calendar


```python
fc5.cal.show.cur_month({optional arg})
```
returns `'March'` without optional arg

With optional arg example:  `fc5.cal.show.cur_month(3)`
Returns a sliced string, where the length is based on the optional int arg, representing the name of the month ('Mar') of the year it is, based on the 445 calendar'''

<br>

Which month of the year it is based on 445 calendar minus one week


```python
fc5.cal.show.month_of_prior_week({optional arg})
```
returns `'March'` without optional arg

With optional arg example:  `fc5.cal.show.month_of_prior_week(3)`
Returns a sliced string, where the length is based on the optional int arg, representing the name of the month ('Mar') of the year it is, based on the 445 calendar minus one week'''

<br>

Start and end for month to date


```python
fc5.cal.show.month_to_date()
```
Returns a tuple of the start and end date for month to date reports

`('2020-03-01', '2020-03-09')`

<br>


Start and end for month to date most recent week completed


```python
fc5.cal.show.month_to_date_completed()
```

returns a tuple of the start and end date for month to date reports for up to the most completed week

`('2020-03-01', '2020-03-08')`

returns the following if there has not been an entire complete fiscal week for that month. 

`'Not available yet!'`

<br>

Start and end for year to date


```python
fc5.cal.show.year_to_date()
```

returns a tuple 

`('2020-02-02', '2020-03-07')`

<br>

Start and end for year to date most recent week completed


```python
fc5.cal.show.year_to_date_completed
```

returns a tuple 

`('2020-02-02', '2020-02-29')`

<br>

Start and end dates for completed quarters.

1 for Q1, 2 for Q2, 3 for Q3, 4 for Q4

arg is int value for quarter indicated above. `fc5.cal.show.quarter_dates(arg)`


```python
fc5.cal.show.quarter_dates(1)
```

returns a tuple 

`('2020-02-02', '2020-05-02')`

<br>

Start and end for quarter to date.

1 for Q1, 2 for Q2, 3 for Q3, 4 for Q4

arg is int value for quarter above. `fc5.cal.show.quarter_to_date(arg)`


```python
fc5.cal.show.quarter_to_date(1)
```

returns a tuple 

`('2020-02-02', '2020-03-07')`

returns the following if the current date is before the requested quarter 

`'Quarter not available!'`

<br>

To view the entire calendar after you have initialized it.

`print(fc5.cal)`


## Authors
Dv8edRoute - Original code

## License
MIT

## Acknowledgments


