From 2eed2935ace9eb94d4c352ee815866fa2d5a9201 Mon Sep 17 00:00:00 2001
From: clausherther <claus@calogica.com>
Date: Sun, 6 Mar 2022 16:29:37 -0800
Subject: [PATCH 1/4] Update README

---
 README.md | 676 ++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 579 insertions(+), 97 deletions(-)

diff --git a/README.md b/README.md
index 22d2669..faf6390 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
 # dbt-date
+
 Extension package for [**dbt**](https://github.com/dbt-labs/dbt) to handle date logic and calendar functionality.
 
-FYI: this package includes [**dbt-utils**](https://github.com/dbt-labs/dbt-utils) so there's no need to also import dbt-utils in your local project. (In fact, you may get an error if you do.)
+FYI: this package includes [**dbt-utils**](https://github.com/dbt-labs/dbt-utils) so there"s no need to also import dbt-utils in your local project. (In fact, you may get an error if you do.)
 
 Include in `packages.yml`
 
@@ -22,258 +23,739 @@ For example, in `packages.yml`, you will need to include the relevant package:
 ```
 
 And reference in the dispatch list for `dbt_utils` in `dbt_project.yml`:
+
 ```yaml
 vars:
     dbt_utils_dispatch_list: [spark_utils]
 ```
 
 ## Variables
+
 The following variables need to be defined in your `dbt_project.yml` file:
 
-`'dbt_date:time_zone': 'America/Los_Angeles'`
+```yaml
+vars:
+    "dbt_date:time_zone": "America/Los_Angeles"
+```
 
 You may specify [any valid timezone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) in place of `America/Los_Angeles`.
 For example, use `America/New_York` for East Coast Time.
 
-## Macros
+## Available Macros
 
 ### Date Dimension
 
-#### get_date_dimension ([source](macros/get_date_dimension.sql))
-Returns query to build date dimension from/to specified dates, including a number of useful columns based on each date.
+- [get_base_dates](#get_base_dates)
+- [get_date_dimension](#get_date_dimension)
+
+### Calendar Date
+
+- [convert_timezone](#convert_timezone)
+- [date_part](#date_part)
+- [day_name](#day_name)
+- [day_of_month](#day_of_month)
+- [day_of_week](#day_of_week)
+- [day_of_year](#day_of_year)
+- [from_unixtimestamp](#from_unixtimestamp)
+- [iso_week_end](#iso_week_end)
+- [iso_week_of_year](#iso_week_of_year)
+- [iso_week_start](#iso_week_start)
+- [last_month_name](#last_month_name)
+- [last_month_number](#last_month_number)
+- [last_month_start_date](#last_month_start_date)
+- [last_month](#last_month)
+- [last_week](#last_week)
+- [month_name](#month_name)
+- [n_days_ago](#n_days_ago)
+- [n_days_away](#n_days_away)
+- [n_months_ago](#n_months_ago)
+- [n_months_away](#n_months_away)
+- [n_weeks_ago](#n_weeks_ago)
+- [n_weeks_away](#n_weeks_away)
+- [next_month_name](#next_month_name)
+- [next_month_number](#next_month_number)
+- [next_month_start_date](#next_month_start_date)
+- [next_month](#next_month)
+- [next_week_start_date](#next_week_start_date)
+- [next_week](#next_week)
+- [now](#now)
+- [periods_since](#periods_since)
+- [to_unixtimestamp](#to_unixtimestamp)
+- [today](#today)
+- [tomorrow](#tomorrow)
+- [week_end](#week_end)
+- [week_of_year](#week_of_year)
+- [week_start](#week_start)
+- [yesterday](#yesterday)
+
+## Fiscal Date
+
+- [get_fiscal_periods](#get_fiscal_periods)
+- [get_fiscal_year_dates](#get_fiscal_year_dates)
+
+## Documentation
+
+### [get_base_dates](macros/get_base_dates.sql)(`start_date=None, end_date=None, n_dateparts=None, datepart="day"`)
+
+A wrapper around `dbt_utils.date_spine` that allows you to specify either `start_date` and `end_date` for your date spine, or specify a number of periods (`n_dateparts`) in the past from today.
+
+Usage:
+
+```sql
+{{ dbt_date.get_base_dates(start_date="2015-01-01", end_date="2022-12-31") }}
+```
+
+or to build a daily date dimension for the last 3 years:
+
+```sql
+{{ dbt_date.get_base_dates(n_dateparts=365*3, datepart="day") }}
+```
+
+### [get_date_dimension](macros/get_date_dimension.sql)(`start_date, end_date`)
+
+Returns a query to build date dimension from/to specified dates, including a number of useful columns based on each date.
 See the [example model](integration_tests/models/dim_date.sql) for details.
 
 Usage:
 
-```python
-{{ dbt_date.get_date_dimension('2015-01-01', '2022-12-31') }}
+```sql
+{{ dbt_date.get_date_dimension("2015-01-01", "2022-12-31") }}
 ```
 
 ### Fiscal Periods
 
-#### get_fiscal_periods ([source](macros/fiscal_date/get_fiscal_periods.sql))
-Returns query to build a fiscal period calendar based on the 4-5-4 week retail period concept.
+### [get_fiscal_periods](macros/fiscal_date/get_fiscal_periods.sql)(`dates, year_end_month, week_start_day, shift_year=1`)
+
+Returns a query to build a fiscal period calendar based on the 4-5-4 week retail period concept.
 See the [example model](integration_tests/models/dim_date_fiscal.sql) for details and this [blog post](https://calogica.com/sql/dbt/2018/11/15/retail-calendar-in-sql.html) for more context on custom business calendars.
 
 Usage:
 
-```python
-{{ dbt_date.get_fiscal_periods(ref('dates'), year_end_month, week_start_day) }}
+```sql
+{{ dbt_date.get_fiscal_periods(ref("dates"), year_end_month, week_start_day) }}
 ```
+
 Note: the first parameter expects a dbt `ref` variable, i.e. a reference to a model containing the necessary date dimension attributes, which can be generated via the `get_date_dimension` macro (see above).
 
 ### Date
 
-#### convert_timezone ([source](macros/calendar_date/convert_timezone.sql))
+### [convert_timezone](macros/calendar_date/convert_timezone.sql)( `column, target_tz=None, source_tz=None`)
+
 Cross-database implemention of convert_timezone function.
 
 Usage:
 
-```python
-{{ dbt_date.convert_timezone('my_column') }}
+```sql
+{{ dbt_date.convert_timezone("my_column") }}
 ```
 
 or, specify a target timezone:
 
-```python
-{{ dbt_date.convert_timezone('my_column', 'America/New_York') }}
+```sql
+{{ dbt_date.convert_timezone("my_column", "America/New_York") }}
 ```
 
 or, also specify a source timezone:
 
-```python
-{{ dbt_date.convert_timezone('my_column', 'America/New_York', 'UTC') }}
+```sql
+{{ dbt_date.convert_timezone("my_column", "America/New_York", "UTC") }}
 ```
 
 Using named parameters, we can also specify the source only and rely on the configuration parameter for the target:
 
-```python
-{{ dbt_date.convert_timezone('my_column', source_tz='UTC') }}
+```sql
+{{ dbt_date.convert_timezone("my_column", source_tz="UTC") }}
 ```
 
-#### date_part ([source](macros/calendar_date/date_part.sql))
+### [date_part](macros/calendar_date/date_part.sql)(`datepart, date`)
+
 Extracts date parts from date.
 
 Usage:
 
-```python
-{{ dbt_date.date_part('dayofweek', 'date_day') }} as day_of_week
+```sql
+{{ dbt_date.date_part("dayofweek", "date_col") }} as day_of_week
 ```
 
-#### day_name ([source](macros/calendar_date/day_name.sql))
+### [day_name](macros/calendar_date/day_name.sql)(`date, short=True`)
+
 Extracts name of weekday from date.
 
 Usage:
 
-```python
-{{ dbt_date.day_name('date_day', short=true) }} as day_of_week_short_name,
-{{ dbt_date.day_name('date_day', short=false) }} as day_of_week_long_name
+```sql
+{{ dbt_date.day_name("date_col") }} as day_of_week_short_name
+```
+
+```sql
+{{ dbt_date.day_name("date_col", short=true) }} as day_of_week_short_name
+```
+
+```sql
+{{ dbt_date.day_name("date_col", short=false) }} as day_of_week_long_name
+```
+
+### [day_of_month](macros/calendar_date/day_of_month.sql)(`date`)
+
+Extracts day of the month from a date (e.g. `2022-03-06` --> `6`).
+
+Usage:
+
+```sql
+{{ dbt_date.day_of_month("date_col") }} as day_of_month
+```
+
+### [day_of_week](macros/calendar_date/day_of_week.sql)(`date, isoweek=true`)
+
+Extracts day of the week *number* from a date, starting with **1**.
+By default, uses `isoweek=True`, i.e. assumes week starts on *Monday*.
+
+Usage:
+
+```sql
+{{ dbt_date.day_of_week("'2022-03-06'") }} as day_of_week_iso
+```
+
+returns: **7** (Sunday is the *last* day of the ISO week)
+
+```sql
+{{ dbt_date.day_of_week("'2022-03-06'", isoweek=False) }} as day_of_week
+```
+
+returns: **1** (Sunday is the *first* day of the non-ISO week)
+
+### [day_of_year](macros/calendar_date/day_of_year.sql)(`date`)
+
+Extracts day of the year from a date (e.g. `2022-02-02` --> `33`).
+
+Usage:
+
+```sql
+{{ dbt_date.day_of_year("date_col") }} as day_of_year
+```
+
+or
+
+```sql
+{{ dbt_date.day_of_year("'2022-02-02'") }} as day_of_year
+```
+
+returns: **33**
+
+### [from_unixtimestamp](macros/calendar_date/from_unixtimestamp.sql)(`epochs, format="seconds"`)
+
+Converts an `epoch` into a timestamp. The default for `format` is `seconds`, which can overriden depending your data"s epoch format.
+
+Usage:
+
+```sql
+{{ dbt_date.from_unixtimestamp("epoch_column") }} as timestamp_column
+```
+
+```sql
+{{ dbt_date.from_unixtimestamp("epoch_column", format="milliseconds") }} as timestamp_column
+```
+
+See also: [to_unixtimestamp](#to_unixtimestamp)
+
+### [iso_week_end](macros/calendar_date/iso_week_end.sql)(`date=None, tz=None`)
+
+Computes the week ending date using ISO format, i.e. week ending **Sunday**.
+
+Usage:
+
+```sql
+{{ dbt_date.iso_week_end("date_col") }} as iso_week_end_date
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.iso_week_end("date_col", tz="America/New_York") }} as iso_week_end_date
+```
+
+### [iso_week_of_year](macros/calendar_date/iso_week_of_year.sql)(`date=None, tz=None`
+
+Computes the week of the year using ISO format, i.e. week ending **Sunday**.
+
+Usage:
+
+```sql
+{{ dbt_date.iso_week_of_year("date_col") }} as iso_week_of_year
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.iso_week_of_year("date_col", tz="America/New_York") }} as iso_week_of_year
+```
+
+### [iso_week_start](macros/calendar_date/iso_week_start.sql)(`date=None, tz=None`
+
+Computes the week starting date using ISO format, i.e. week starting **Monday**.
+
+Usage:
+
+```sql
+{{ dbt_date.iso_week_start("date_col") }} as iso_week_start_date
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.iso_week_start("date_col", tz="America/New_York") }} as iso_week_start_date
+```
+
+### [last_month_name](macros/calendar_date/last_month_name.sql)(`short=True, tz=None`)
+
+Extracts the name of the prior month from a date.
+
+```sql
+{{ dbt_date.last_month_name() }} as last_month_short_name
+```
+
+```sql
+{{ dbt_date.last_month_name(short=true) }} as last_month_short_name
+```
+
+```sql
+{{ dbt_date.last_month_name(short=false) }} as last_month_long_name
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.last_month_name(tz="America/New_York") }} as last_month_short_name
+```
+
+### [last_month_number](macros/calendar_date/last_month_number.sql)(`tz=None`)
+
+Returns the number of the prior month.
+
+```sql
+{{ dbt_date.last_month_number() }}
 ```
 
-#### last_week ([source](macros/calendar_date/last_week.sql))
-Convenience function to get the start date of last week
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.last_month_number(tz="America/New_York") }}
+```
+
+### [last_month](macros/calendar_date/last_month.sql)(`tz=None`)
+
+Returns the start date of the prior month.
+
+```sql
+{{ dbt_date.last_month() }} as last_month_start_date
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.last_month(tz="America/New_York") }} as last_month_start_date
+```
+
+### [last_week](macros/calendar_date/last_week.sql)(`tz=None`)
+
+Convenience function to get the start date of last week (non-ISO)
 
 Wraps:
-```python
+
+```sql
 {{ dbt_date.n_weeks_ago(1, tz) }}
 ```
 
 Usage:
-```python
-{{ dbt_date.last_week()) }}
+
+```sql
+{{ dbt_date.last_week()) }} as last_week_start_date
 ```
-```python
-{{ dbt_date.last_week(tz='America/New_York)) }}
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.last_week(tz="America/New_York)) }} as last_week_start_date
 ```
 
-#### month_name ([source](macros/calendar_date/month_name.sql))
-Extracts name of month from date.
+### [month_name](macros/calendar_date/month_name.sql)(`date, short=True, tz=None`)
+
+Extracts the name of the month from a date.
 
-```python
-{{ dbt_date.month_name('date_day', short=true) }} as month_short_name,
-{{ dbt_date.month_name('date_day', short=false) }} as month_long_name
+```sql
+{{ dbt_date.month_name(date_col) }} as month_short_name
 ```
 
-#### n_days_ago ([source](macros/calendar_date/n_days_ago.sql))
-Gets date _n_ days ago, based on local date.
+```sql
+{{ dbt_date.month_name(date_col, short=true) }} as month_short_name
+```
+
+```sql
+{{ dbt_date.month_name(date_col, short=false) }} as month_long_name
+```
+
+### [n_days_ago](macros/calendar_date/n_days_ago.sql)(`n, date=None, tz=None`)
+
+Gets date *n* days ago, based on local date.
 
 Usage:
 
-```python
+```sql
 {{ dbt_date.n_days_ago(7) }}
 ```
 
-#### n_days_away ([source](macros/calendar_date/n_days_away.sql))
-Gets date _n_ days from now, based on local date.
+Alternatively, you can specify a date column instead of defaulting the local date:
+
+```sql
+{{ dbt_date.n_days_ago(7, date="date_col") }}
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.n_days_ago(7, tz="America/New_York)) }}
+```
+
+### [n_days_away](macros/calendar_date/n_days_away.sql)(`n, date=None, tz=None`)
+
+Gets date *n* days away, based on local date.
 
 Usage:
 
-```python
+```sql
 {{ dbt_date.n_days_away(7) }}
 ```
 
-#### n_months_ago ([source](macros/calendar_date/n_months_ago.sql))
-Gets date _n_ months ago, based on local date.
+Alternatively, you can specify a date column instead of defaulting the local date:
+
+```sql
+{{ dbt_date.n_days_away(7, date="date_col") }}
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.n_days_away(7, tz="America/New_York)) }}
+```
+
+### [n_months_ago](macros/calendar_date/n_months_ago.sql)(`n, tz=None`)
+
+Gets date *n* months ago, based on local date.
 
 Usage:
 
-```python
+```sql
 {{ dbt_date.n_months_ago(12) }}
 ```
 
-#### n_months_away ([source](macros/calendar_date/n_months_away.sql))
-Gets date _n_ months from now, based on local date.
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.n_months_ago(12, tz="America/New_York)) }}
+```
+
+### [n_months_away](macros/calendar_date/n_months_away.sql)(`n, tz=None`)
+
+Gets date *n* months away, based on local date.
 
 Usage:
 
-```python
-{{ dbt_date.n_months_away(12) }}
+```sql
+{{ dbt_date.n_months_ago(12) }}
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.n_months_away(12, tz="America/New_York)) }}
 ```
 
-#### n_weeks_ago ([source](macros/calendar_date/n_weeks_ago.sql))
-Gets date _n_ weeks ago, based on local date.
+### [n_weeks_ago](macros/calendar_date/n_weeks_ago.sql)(`n, tz=None`)
+
+Gets date *n* weeks ago, based on local date.
 
 Usage:
 
-```python
-{{ dbt_date.n_weeks_ago(4) }}
+```sql
+{{ dbt_date.n_weeks_ago(12) }}
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.n_weeks_ago(12, tz="America/New_York)) }}
 ```
 
-#### n_weeks_away ([source](macros/calendar_date/n_weeks_away.sql))
-Gets date _n_ weeks from now, based on local date.
+### [n_weeks_away](macros/calendar_date/n_weeks_away.sql)(`n, tz=None`)
+
+Gets date *n* weeks away, based on local date.
 
 Usage:
 
-```python
-{{ dbt_date.n_weeks_away(4) }}
+```sql
+{{ dbt_date.n_weeks_away(12) }}
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.n_weeks_away(12, tz="America/New_York)) }}
+```
+
+### [next_month_name](macros/calendar_date/next_month_name.sql)(`short=True, tz=None`)
+
+Extracts the name of the next month from a date.
+
+```sql
+{{ dbt_date.next_month_name() }} as next_month_short_name
+```
+
+```sql
+{{ dbt_date.next_month_name(short=true) }} as next_month_short_name
+```
+
+```sql
+{{ dbt_date.next_month_name(short=false) }} as next_month_long_name
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.next_month_name(tz="America/New_York") }} as next_month_short_name
 ```
 
-#### now ([source](macros/calendar_date/now.sql))
-Gets time based on local timezone (specified). Default is "America/Los_Angeles".
+### [next_month_number](macros/calendar_date/next_month_number.sql)(`tz=None`)
+
+Returns the number of the next month.
+
+```sql
+{{ dbt_date.next_month_number() }}
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.next_month_number(tz="America/New_York") }}
+```
+
+### [next_month](macros/calendar_date/next_month.sql)(`tz=None`)
+
+Returns the start date of the next month.
+
+```sql
+{{ dbt_date.next_month() }} as next_month_start_date
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.next_month(tz="America/New_York") }} as next_month_start_date
+```
+
+### [next_week](macros/calendar_date/next_week.sql)(`tz=None`)
+
+Convenience function to get the start date of next week (non-ISO)
+
+Wraps:
+
+```sql
+{{ dbt_date.n_weeks_away(1, tz) }}
+```
 
 Usage:
 
-```python
-{{ dbt_date.now() }}
+```sql
+{{ dbt_date.next_week()) }} as next_week_start_date
 ```
 
-or, specify a timezone:
+or, optionally, you can override the default timezone:
 
-```python
-{{ dbt_date.now('America/New_York') }}
+```sql
+{{ dbt_date.next_week(tz="America/New_York") }}  as next_week_start_date
 ```
 
-#### periods_since ([source](macros/calendar_date/periods_since.sql))
-Returns the number of periods since a specified date.
+### [now](macros/calendar_date/now.sql)(`tz=None`)
+
+Gets current timestamp based on local timezone (specified). Default is "America/Los_Angeles".
 
 Usage:
 
-```python
-{{ dbt_date.periods_since('my_date_column', period_name='day' }}
+```sql
+{{ dbt_date.now() }}
 ```
 
-The macro used the `dbt_date:time_zone` variable from `dbt_project.yml` to calculate today's date.
-Alternatively, a timezone can be specified via the `tz` parameter:
+or, optionally, you can override the default timezone:
 
-```python
-{{ dbt_date.periods_since('my_timestamp_column', period_name='minute', tz='UTC' }}
+```sql
+{{ dbt_date.now("America/New_York") }}
 ```
 
-#### this_week ([source](macros/calendar_date/this_week.sql))
-Gets current week start date, based on local date.
+### [periods_since](macros/calendar_date/periods_since.sql)(`date_col, period_name='day', tz=None`)
+
+Returns the number of periods since a specified date or to `now`.
 
 Usage:
 
-```python
-{{ dbt_date.this_week() }}
+```sql
+{{ dbt_date.periods_since("my_date_column", period_name="day" }}
 ```
 
-#### to_unixtimestamp ([source](macros/calendar_date/to_unixtimestamp.sql))
+or,
+
+```sql
+{{ dbt_date.periods_since("my_timestamp_column", period_name="minute" }}
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.periods_since("my_timestamp_column", period_name="minute", tz="UTC" }}
+```
+
+### [to_unixtimestamp](macros/calendar_date/to_unixtimestamp.sql)(`timestamp`)
+
 Gets Unix timestamp (epochs) based on provided timestamp.
 
 Usage:
 
-```python
-{{ dbt_date.to_unixtimestamp('my_timestamp_column') }}
+```sql
+{{ dbt_date.to_unixtimestamp("my_timestamp_column") }}
 ```
 
-```python
+```sql
 {{ dbt_date.to_unixtimestamp(dbt_date.now()) }}
 ```
 
-#### today ([source](macros/calendar_date/today.sql))
-Gets date based on local timezone (specified). Package default is "America/Los_Angeles". The default must be specified in `dbt_project.yml`, in the `'dbt_date:time_zone'` variable. e.g `'dbt_date:time_zone': 'America/New_York'`.
+### [today](macros/calendar_date/today.sql)(`tz=None`)
+
+Gets date based on local timezone.
 
 Usage:
 
-```python
+```sql
 {{ dbt_date.today() }}
 ```
 
-or, specify a timezone:
-```python
-{{ dbt_date.today('America/New_York') }}
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.today("America/New_York") }}
 ```
 
-#### tomorrow ([source](macros/calendar_date/tomorrow.sql))
+### [tomorrow](macros/calendar_date/tomorrow.sql)(`date=None, tz=None`)
+
 Gets tomorrow's date, based on local date.
 
 Usage:
 
-```python
+```sql
 {{ dbt_date.tomorrow() }}
 ```
 
-or, specify a timezone:
-```python
-{{ dbt_date.tomorrow('America/New_York') }}
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.tomorrow(tz="America/New_York") }} as date_tomorrow
+```
+
+Alternatively, you can also override the anchor date from the default `today` to some other date:
+
+```sql
+{{ dbt_date.tomorrow(date="date_col", tz="America/New_York") }} as date_tomorrow
 ```
 
-#### yesterday ([source](macros/calendar_date/yesterday.sql))
+### [week_end](macros/calendar_date/week_end.sql)(`date=None, tz=None`)
+
+Computes the week ending date using standard (US) format, i.e. week starting **Sunday**.
+
+Usage:
+
+If `date` is not specified, the date anchor defaults to `today`.
+
+```sql
+{{ dbt_date.week_end() }} as week_end_date
+```
+
+or specify a date (column):
+
+```sql
+{{ dbt_date.week_end("date_col") }} as week_end_date
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.week_end("date_col", tz="America/New_York") }} as week_end_date
+```
+
+### [week_of_year](macros/calendar_date/week_of_year.sql)(`date=None, tz=None`)
+
+Computes the week of the year using standard (US) format, i.e. week ending **Saturday**.
+
+Usage:
+
+If `date` is not specified, the date anchor defaults to `today`.
+
+```sql
+{{ dbt_date.week_of_year() }} as week_of_year
+```
+
+or specify a date (column):
+
+```sql
+{{ dbt_date.week_of_year("date_col") }} as week_of_year
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.week_of_year("date_col", tz="America/New_York") }} as week_of_year
+```
+
+### [week_start](macros/calendar_date/week_start.sql)(`date=None, tz=None`)
+
+Computes the week starting date using standard (US) format, i.e. week starting **Sunday**.
+
+Usage:
+
+If `date` is not specified, the date anchor defaults to `today`.
+
+```sql
+{{ dbt_date.week_start() }} as week_start
+```
+
+or specify a date (column):
+
+```sql
+{{ dbt_date.week_start("date_col") }} as week_start
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.week_start("date_col", tz="America/New_York") }} as week_start
+```
+
+### [yesterday](macros/calendar_date/yesterday.sql)(`date=None, tz=None`)
+
 Gets yesterday's date, based on local date.
 
 Usage:
 
-```python
-{{ dbt_date.yesterday() }}
+If `date` is not specified, the date anchor defaults to `today`.
+
+```sql
+{{ dbt_date.yesterday() }} as date_yesterday
+```
+
+or specify a date (column):
+
+```sql
+{{ dbt_date.yesterday("date_col") }} as date_yesterday
+```
+
+or, optionally, you can override the default timezone:
+
+```sql
+{{ dbt_date.yesterday(tz="America/New_York") }} as date_yesterday
 ```

From c98afd7ab2281cf633c1c05e4e170959461ae975 Mon Sep 17 00:00:00 2001
From: clausherther <claus@calogica.com>
Date: Sun, 6 Mar 2022 16:30:02 -0800
Subject: [PATCH 2/4] clean up unused macros

---
 macros/calendar_date/last_month_name.sql       | 4 ++--
 macros/calendar_date/last_month_start_date.sql | 3 ---
 macros/calendar_date/next_month_start_date.sql | 3 ---
 macros/calendar_date/next_week_start_date.sql  | 3 ---
 4 files changed, 2 insertions(+), 11 deletions(-)
 delete mode 100644 macros/calendar_date/last_month_start_date.sql
 delete mode 100644 macros/calendar_date/next_month_start_date.sql
 delete mode 100644 macros/calendar_date/next_week_start_date.sql

diff --git a/macros/calendar_date/last_month_name.sql b/macros/calendar_date/last_month_name.sql
index 0fc86e7..fc2e762 100644
--- a/macros/calendar_date/last_month_name.sql
+++ b/macros/calendar_date/last_month_name.sql
@@ -1,3 +1,3 @@
 {%- macro last_month_name(short=True, tz=None) -%}
-{{ dbt_date.month_name(dbt_date.lastnext_month(1, tz), short=short) }}
-{%- endmacro -%}
\ No newline at end of file
+{{ dbt_date.month_name(dbt_date.last_month(1, tz), short=short) }}
+{%- endmacro -%}
diff --git a/macros/calendar_date/last_month_start_date.sql b/macros/calendar_date/last_month_start_date.sql
deleted file mode 100644
index 1c90a9e..0000000
--- a/macros/calendar_date/last_month_start_date.sql
+++ /dev/null
@@ -1,3 +0,0 @@
-{%- macro last_month_start_date(tz=None) -%}
-{{ dbt_date.last_month(1, tz) }}
-{%- endmacro -%}
\ No newline at end of file
diff --git a/macros/calendar_date/next_month_start_date.sql b/macros/calendar_date/next_month_start_date.sql
deleted file mode 100644
index 6f0ff3b..0000000
--- a/macros/calendar_date/next_month_start_date.sql
+++ /dev/null
@@ -1,3 +0,0 @@
-{%- macro next_month_start_date(tz=None) -%}
-{{ dbt_date.next_month(1, tz) }}
-{%- endmacro -%}
\ No newline at end of file
diff --git a/macros/calendar_date/next_week_start_date.sql b/macros/calendar_date/next_week_start_date.sql
deleted file mode 100644
index 2289a33..0000000
--- a/macros/calendar_date/next_week_start_date.sql
+++ /dev/null
@@ -1,3 +0,0 @@
-{%- macro next_week_start_date(tz=None) -%}
-{{ dbt_date.next_week(1, tz) }}
-{%- endmacro -%}
\ No newline at end of file

From 753e515f28dba3aea889f4cd0ac011b0ed6fe586 Mon Sep 17 00:00:00 2001
From: clausherther <claus@calogica.com>
Date: Sun, 6 Mar 2022 16:30:19 -0800
Subject: [PATCH 3/4] Update anchor to timestamp

---
 macros/calendar_date/periods_since.sql | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/macros/calendar_date/periods_since.sql b/macros/calendar_date/periods_since.sql
index d2160f4..ffd56b3 100644
--- a/macros/calendar_date/periods_since.sql
+++ b/macros/calendar_date/periods_since.sql
@@ -1,3 +1,3 @@
 {%- macro periods_since(date_col, period_name='day', tz=None) -%}
-{{ dbt_utils.datediff(date_col, dbt_date.today(tz), period_name) }}
-{%- endmacro -%}
\ No newline at end of file
+{{ dbt_utils.datediff(date_col, dbt_date.now(tz), period_name) }}
+{%- endmacro -%}

From 4fd844d64e334f0c0de606a49d62d609019e28ed Mon Sep 17 00:00:00 2001
From: clausherther <claus@calogica.com>
Date: Sun, 6 Mar 2022 16:35:15 -0800
Subject: [PATCH 4/4] Update README

---
 README.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index faf6390..32dfb90 100644
--- a/README.md
+++ b/README.md
@@ -260,7 +260,7 @@ See also: [to_unixtimestamp](#to_unixtimestamp)
 
 ### [iso_week_end](macros/calendar_date/iso_week_end.sql)(`date=None, tz=None`)
 
-Computes the week ending date using ISO format, i.e. week ending **Sunday**.
+Computes the week ending date using ISO format, i.e. week starting **Monday** and ending **Sunday**.
 
 Usage:
 
@@ -274,9 +274,9 @@ or, optionally, you can override the default timezone:
 {{ dbt_date.iso_week_end("date_col", tz="America/New_York") }} as iso_week_end_date
 ```
 
-### [iso_week_of_year](macros/calendar_date/iso_week_of_year.sql)(`date=None, tz=None`
+### [iso_week_of_year](macros/calendar_date/iso_week_of_year.sql)(`date=None, tz=None`)
 
-Computes the week of the year using ISO format, i.e. week ending **Sunday**.
+Computes the week of the year using ISO format, i.e. week starting **Monday**.
 
 Usage:
 
@@ -290,7 +290,7 @@ or, optionally, you can override the default timezone:
 {{ dbt_date.iso_week_of_year("date_col", tz="America/New_York") }} as iso_week_of_year
 ```
 
-### [iso_week_start](macros/calendar_date/iso_week_start.sql)(`date=None, tz=None`
+### [iso_week_start](macros/calendar_date/iso_week_start.sql)(`date=None, tz=None`)
 
 Computes the week starting date using ISO format, i.e. week starting **Monday**.
 
@@ -690,7 +690,7 @@ or, optionally, you can override the default timezone:
 
 ### [week_of_year](macros/calendar_date/week_of_year.sql)(`date=None, tz=None`)
 
-Computes the week of the year using standard (US) format, i.e. week ending **Saturday**.
+Computes the week of the year using standard (US) format, i.e. week starting **Sunday** and ending **Saturday**.
 
 Usage: