---
description: Finter Trading day Calendar Guide
---

# Calendar

Finter is proud to offer a new, free-to-use feature for our users: the **Trading day Calendar**. Access to trading day information is often restricted and difficult to obtain, but we believe in providing our users with the tools they need without any cost. The trading day data is updated weekly to ensure you have the most current information at your fingertips.

### Import Statements

To take advantage of the Trading day Calendar, you'll need to import the necessary functions and classes. Here's how you can do it:

```python
from finter.calendar import (
    iter_trading_days, iter_holidays, iter_days, TradingDay, Code
)
```

### Available Exchanges

The Calendar feature currently supports the following exchanges: `krx` and `us`. For all functions, unless specified otherwise, the default `exchange` argument is set to `krx`.

#### Code

The `Code` class is an enum that helps categorize the days according to the trading status. It is used in conjunction with other functions to filter the days based on the trading activity. You can retrieve all the enum members and their corresponding values using the following sample code:

```python
>>> Code.get_all_by_dict()
{<Code.ALL_DAY: 0>: 0, <Code.TRADING_DAY: 1>: 1, <Code.HOLIDAY: 2>: 2, <Code.WEEKENDS: 3>: 3}
```

#### iter\_trading\_days

The `iter_trading_days` function is useful for generating a list of all the trading days within a specified date range. It filters out weekends and holidays, providing only the days when the market was open for trading. You can input dates as integers, strings, or `datetime` objects as shown in the sample code below:

```python
from datetime import datetime

# int, str, datetime is available
list(iter_trading_days(20240101, 20240110))
list(iter_trading_days("20240101", "20240110"))
list(iter_trading_days(
    datetime(2024, 1, 1), datetime(2024, 1, 10)
))
[datetime.datetime(2024, 1, 2, 0, 0), datetime.datetime(2024, 1, 3, 0, 0), datetime.datetime(2024, 1, 4, 0, 0), datetime.datetime(2024, 1, 5, 0, 0), datetime.datetime(2024, 1, 8, 0, 0), datetime.datetime(2024, 1, 9, 0, 0), datetime.datetime(2024, 1, 10, 0, 0)]
```

#### iter\_holidays

The `iter_holidays` function is particularly useful for identifying days when the market is closed for reasons other than weekends, such as public holidays or special market closures.

```python
# int, str, datetime is available
# weekend is not included!!

>>> list(iter_holidays(20231223, 20231231, exchange="krx"))
[datetime.datetime(2023, 12, 25, 0, 0), datetime.datetime(2023, 12, 29, 0, 0)]

>>> list(iter_holidays("20231223",  "20231231", exchange="us"))
[datetime.datetime(2023, 12, 25, 0, 0)]
```

#### iter\_days

By providing the desired enum value from `Code`, the `iter_days` function allows you to filter the days to get a list of dates that match the trading day type you are interested in.

```python
>>> list(iter_days(20231223, 20231231, exchange="krx", date_type=2))  # same with iter_holiday
[datetime.datetime(2023, 12, 25, 0, 0), datetime.datetime(2023, 12, 29, 0, 0)]
>>> list(iter_days(20231223, 20231231, exchange="us", date_type=Code.TRADING_DAY.value))  # same with iter_tradingday
[datetime.datetime(2023, 12, 26, 0, 0), datetime.datetime(2023, 12, 27, 0, 0), datetime.datetime(2023, 12, 28, 0, 0), datetime.datetime(2023, 12, 29, 0, 0)]
```

#### TradingDay

The `TradingDay` class is a powerful tool for navigating through trading days. Whether you need to find the previous, next, or a specific number of days away from a given trading day, this class provides methods to easily calculate those dates.

* `last_close`: Returns the most recent closed trading day. The `date` argument must be in the format `%Y%m%d%H%M%S`.
* `upcoming_close`: Returns the nearest upcoming trading day closure. The `date` argument must be in the format `%Y%m%d%H%M%S`.
* `next`: Returns the next trading day after the given date.
* `prev`: Returns the trading day before the given date.
* `day_delta`: Returns the trading day that is `n` business days away from the given date, where `n` can be positive or negative.

```python
>>> TradingDay.prev(20240101, exchange="us")
datetime.datetime(2023, 12, 29, 0, 0)

>>> TradingDay.next(20240101, exchange="us")
datetime.datetime(2024, 1, 2, 0, 0)

>>> TradingDay.last_close(datetime.now(), exchange="krx") # this document is wrote at 20240307 17:42
datetime.datetime(2024, 3, 7, 0, 0)

>>> TradingDay.upcoming_close(datetime.now(), exchange="krx") # this document is wrote at 20240307 17:42
datetime.datetime(2024, 3, 8, 0, 0)

>>> TradingDay.day_delta("20240101", n=-5, exchange="krx")
datetime.datetime(2023, 12, 21, 0, 0)

>>> TradingDay.day_delta("20240101", n=-5, exchange="us")
datetime.datetime(2023, 12, 22, 0, 0)
```

Note that using `TradingDay.last_close` and `TradingDay.upcoming_close` with a `%Y%m%d` format will result in an error:

```python
# Wrong format!!!
>>> TradingDay.last_close(20240101) 
>>> TradingDay.upcoming_close(20240101)

...
AssertionError: '%Y%m%d%H%M%S' format is required
```

Finter is committed to enhancing your financial data experience. We continuously strive to provide you with the most accurate and up-to-date information, so you can make informed decisions with confidence.
