> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pysquirrels.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DateParameterOption

> Parameter option for date widgets

Parameter option for date parameters that can vary based on selection of another parameter.

This class can be imported from the `squirrels.parameter_options` or the `squirrels` module.

## Constructor

Creates a `DateParameterOption` object. Typically used in `pyconfigs/parameters.py`.

```python theme={null}
def __init__(
    self, default_date: str | date, 
    *, min_date: str | date | None = None, max_date: str | date | None = None, 
    date_format: str = '%Y-%m-%d', user_groups: Iterable[Any] | str = frozenset(), 
    parent_option_ids: Iterable[str] | str = frozenset()
) -> None:
```

<Expandable title="arguments" defaultOpen>
  <ResponseField name="default_date" type="str | date" required>
    Default date for this option. Can be provided as a string (parsed using `date_format` argument) or as a `datetime.date` object.
  </ResponseField>

  <ResponseField name="min_date" type="str | date | None" default="None">
    Minimum date constraint. Can be provided as a string (parsed using `date_format` argument), a `datetime.date` object, or None. If None, no minimum date constraint applies.
  </ResponseField>

  <ResponseField name="max_date" type="str | date | None" default="None">
    Maximum date constraint. Can be provided as a string (parsed using `date_format` argument), a `datetime.date` object, or None. If None, no maximum date constraint applies.
  </ResponseField>

  <ResponseField name="date_format" type="str" default="'%Y-%m-%d'">
    Format of the date string when dates are provided as strings. Uses Python's `strftime` format codes (e.g., `%Y-%m-%d` for ISO format, `%m/%d/%Y` for US format).
  </ResponseField>

  <ResponseField name="user_groups" type="Iterable[Any] | str" default="frozenset()">
    User group(s) this option is visible for. Only applies if `user_attribute` is provided to the factory method `create_with_options` associated to the [DateParameter](/references/python/parameters/dateparameter).
  </ResponseField>

  <ResponseField name="parent_option_ids" type="Iterable[str] | str" default="frozenset()">
    Parent option id(s) that must be selected for this option to be visible. Only applies if `parent_name` is provided to the factory method `create_with_options` associated to the [DateParameter](/references/python/parameters/dateparameter).
  </ResponseField>
</Expandable>

## Examples

A `DateParameterOption` object is created in the `pyconfigs/parameters.py` file. It must be created in a function decorated with the `create_with_options` factory method from [DateParameter](/references/python/parameters/dateparameter).

### Usage example in parameters.py

```python highlight="11-15" theme={null}
from squirrels import parameters as p, parameter_options as po
from datetime import date

@p.DateParameter.create_with_options(
    name="report_date", 
    label="Report Date",
    description="Date for the report"
)
def report_date_options():
    return [
        po.DateParameterOption(
            default_date=date(2024, 1, 1),
            min_date=date(2020, 1, 1),
            max_date=date(2024, 12, 31)
        )
    ]
```

In addition, the following are some additional examples for creating a `DateParameterOption` object.

### Using string dates with custom format

This example shows how to specify dates as strings with a custom date format instead of using `datetime.date` objects.

```python highlight="5" theme={null}
po.DateParameterOption(
    default_date="01/15/2024",
    min_date="01/01/2020",
    max_date="12/31/2024",
    date_format="%m/%d/%Y"  # US date format
)
```

### Setting up cascading parameters with varying date ranges

This example shows how to create date options that change their constraints based on the selection of a parent parameter (e.g., different fiscal years with different date ranges).

```python highlight="18,26,32" theme={null}
# Parent parameter for fiscal year
@p.SingleSelectParameter.create_with_options(
    name="fiscal_year", 
    label="Fiscal Year",
    description="Fiscal year for the report"
)
def fiscal_year_options():
    return [
        po.SelectParameterOption(id="fy2023", label="FY 2023"),
        po.SelectParameterOption(id="fy2024", label="FY 2024"),
    ]

# Child date parameter with ranges that vary by fiscal year
@p.DateParameter.create_with_options(
    name="report_date", 
    label="Report Date",
    description="Date within the selected fiscal year",
    parent_name="fiscal_year"  # Name of the parent parameter above
)
def report_date_options():
    return [
        po.DateParameterOption(
            default_date="2023-01-01",
            min_date="2023-01-01",
            max_date="2023-12-31",
            parent_option_ids="fy2023"  # Only applies when "fy2023" is selected
        ),
        po.DateParameterOption(
            default_date="2024-01-01",
            min_date="2024-01-01",
            max_date="2024-12-31",
            parent_option_ids="fy2024"  # Only applies when "fy2024" is selected
        )
    ]
```

### Restricting date ranges by user groups

This example shows how to provide different date range constraints based on user access levels using the `user_groups` parameter.

```python highlight="5,12,17" theme={null}
@p.DateParameter.create_with_options(
    name="transaction_date", 
    label="Transaction Date",
    description="Date to query transactions",
    user_attribute="access_level"
)
def transaction_date_options():
    return [
        po.DateParameterOption(
            default_date=date.today(),
            min_date=date(2025, 1, 1),  # Recent data only
            user_groups=["guest"]  # Guests can only see recent dates
        ),
        po.DateParameterOption(
            default_date=date.today(),
            min_date=date(2020, 1, 1),  # Can see back to 2020
            user_groups=["admin", "member"]  # Members and admins see full history
        )
    ]
```

If custom user fields are defined in `pyconfigs/user.py`, then they can be used to restrict date constraints as well. To do so, the `user_attribute` argument must be prefixed with `custom_fields.`.

```python highlight="5,12,17" theme={null}
@p.DateParameter.create_with_options(
    name="analysis_date", 
    label="Analysis Date",
    description="Date for analysis",
    user_attribute="custom_fields.department"
)
def analysis_date_options():
    return [
        po.DateParameterOption(
            default_date=date.today(),
            min_date=date(2024, 6, 1),  # Recent data only
            user_groups=["sales"]  # Sales team sees only recent dates
        ),
        po.DateParameterOption(
            default_date=date.today(),
            min_date=date(2020, 1, 1),  # Historical data access
            user_groups=["analytics"]  # Analytics team sees full history
        )
    ]
```