Yfinance Cache

https://valueraider.github.io/yfinance-cache
Admin
Yfinance Cache provides a comprehensive caching mechanism for yfinance data, enhancing efficiency...
Tokens:165,004
Snippets:618
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### DataFrame Initialization for Merge Example

Source: https://valueraider.github.io/yfinance-cache/yfinance_cache.html

Initializes two pandas DataFrames, df1 and df2, which will be used in a merge operation. This setup is common for demonstrating join-like functionalities.

```python
import pandas as pd
df1 = pd.DataFrame({'lkey': ['foo', 'bar', 'baz', 'foo'],
                    'value': [1, 2, 3, 5]})
df2 = pd.DataFrame({'rkey': ['foo', 'bar', 'baz', 'foo'],
                    'value': [5, 6, 7, 8]})
df1
df2
```

--------------------------------

### Processing Price Data by Interval

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

Handles data processing based on the specified interval (Week, Day, or other). It calculates 'Week Start' or 'Day Start' for specific intervals and assigns an 'intervalID' for others, determining the grouping column for aggregation.

```python
            df_fine["ctr"] = 0
            if self.interval == yfcd.Interval.Week:
                # df_fine["Week Start"] = df_fine.index.tz_localize(None).to_period("W-SUN").start_time
                weekdays = ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"]
                week_end_day = weekdays[(df_block.index[0].weekday() + 7 - 1) % 7]
                df_fine["Week Start"] = df_fine.index.tz_localize(None).to_period("W-"+week_end_day).start_time
                grp_col = "Week Start"
            elif self.interval == yfcd.Interval.Days1:
                df_fine["Day Start"] = pd.to_datetime(df_fine.index.date)
                grp_col = "Day Start"
            else:
                df_fine.loc[df_fine.index.isin(df_block.index), "ctr"] = 1
                df_fine["intervalID"] = df_fine["ctr"].cumsum()
                df_fine = df_fine.drop("ctr", axis=1)
                grp_col = "intervalID"
            # df_fine = df_fine[~df_fine[price_cols].isna().all(axis=1)]
```

--------------------------------

### Get Release Dates

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_ticker.html

Retrieves financial release dates (annual or quarterly). Includes options to control data fetching and caching.

```python

    def get_release_dates(self, period='quarterly', as_df=False, check=True):
        if period not in ['annual', 'quarterly']:
            raise ValueError(f'period argument must be "annual" or "quarterly", not "{period}"')
        if period == 'annual':
            period = yfcd.ReportingPeriod.Full
        else:
            period = yfcd.ReportingPeriod.Interim

        releases = self._financials_manager.get_release_dates(period, as_df, refresh=True, check=check)
        if releases is None:
            return releases

```

--------------------------------

### DateRangeEstimate Initialization

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_dat.html

Initializes a DateRangeEstimate object with start and end dates and a confidence level. Includes type validation for input parameters.

```python
def __init__(self, start, end, confidence):
        if (start is not None) and not isinstance(start, date):
            raise Exception("'start' must be a 'date' object or None, not {0}".format(type(start)))
        if (end is not None) and not isinstance(end, date):
            raise Exception("'end' must be a 'date' object or None, not {0}".format(type(end)))
        if not isinstance(confidence, Confidence):
            raise Exception("'confidence' must be a 'Confidence' object, not {0}".format(type(confidence)))
        self.start = start
        self.end = end
        self.confidence = confidence
        self.uncertainty = confidence_to_buffer[confidence]
```

--------------------------------

### Get Calendar Information

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_ticker.html

Retrieves calendar information using the financial manager.

```python
return self._financials_manager.get_calendar()
```

--------------------------------

### Get Trading Calendar Data with Cache

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_time.html

Retrieves the trading calendar for a given exchange and date range, utilizing a cache for efficiency.

```python
cal = GetCalendarViaCache(exchange, start_d, end_d)
```

--------------------------------

### Get Financial Table with Interval Reporting

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_financials_manager.html

Retrieves a financial table for a given financial type and reporting period (Interim). It then uses this table to determine the interval between financial reports.

```python
    def _get_interval(self, finType, refresh=True):
        debug = False
        # debug = True

        if debug:
            print(f"_get_interval({finType})")

        if not isinstance(finType, yfcd.Financials):
            raise Exception('Argument finType must be type Financials')

        tbl = self._get_fin_table(finType, yfcd.ReportingPeriod.Interim, refresh)

        return self._get_interval_from_table(tbl)
```

--------------------------------

### TimedeltaRangeEstimate Initialization and Representation

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_dat.html

Initializes a TimedeltaRangeEstimate object with start and end time deltas and confidence level. Ensures correct type checking and ordering of time deltas. Provides string and representation methods.

```python
[docs]
class TimedeltaRangeEstimate():
    def __init__(self, td1, td2, confidence):
        if not isinstance(confidence, Confidence):
            raise Exception("'confidence' must be a 'Confidence' object, not {0}".format(type(confidence)))
        if (td1 is not None) and not isinstance(td1, (timedelta, pd.Timedelta)):
            raise Exception("'td1' must be a 'timedelta' object or None, not {0}".format(type(td1)))
        if (td2 is not None) and not isinstance(td2, (timedelta, pd.Timedelta)):
            raise Exception("'td2' must be a 'timedelta' object or None, not {0}".format(type(td2)))
        if td2 <= td1:
            swap = td1 ; td1 = td2 ; td2 = swap
        self.td1 = td1
        self.td2 = td2
        self.confidence = confidence
        self.uncertainty = confidence_to_buffer[confidence]

    def __str__(self):
        s = f"TimedeltaRangeEstimate {self.td1} -> {self.td2} (conf={self.confidence}/2)"
        return s

    def __repr__(self):
        return self.__str__()

    def __abs__(self):
        return TimedeltaRangeEstimate(abs(self.td1), abs(self.td2), self.confidence)
```

--------------------------------

### Initialize Debugging and Logging for Sparse Fetching

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

Sets up debugging flags and logs the entry into the _fetchAndAddRanges_sparse method. It enables tracing if configured or prints a debug message.

```python
debug_yfc = self._debug
        # debug_yfc = True

        log_msg = f"_fetchAndAddRanges_sparse(prepost={prepost})"
        if yfcl.IsTracingEnabled():
            yfcl.TraceEnter(log_msg)
        elif debug_yfc:
            print(log_msg)
```

--------------------------------

### Get Exchange Calendar via Cache

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_time.html

Retrieves an exchange calendar, applying caching for performance. It takes an exchange name and a date range (start and optional end) as input.

```python
@lru_cache(maxsize=1000)
def GetCalendarViaCache(exchange, start, end=None):
    global calCache

```

--------------------------------

### Calculate and Cache Release Dates

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_financials_manager.html

This snippet demonstrates the logic for calculating release dates, checking cache validity, and storing the results. It handles cases where cached data is stale and needs recalculation.

```python
            # Check if cached release dates need a recalc
            if md['CalcDate'] < (dt_now - max_age):
                prev_r, next_r = None, None
                for i in range(len(releases)-1):
                    r0 = releases[i]
                    r1 = releases[i+1]
                    try:
                        r_is_history = r0.release_date < d_exchange
                    except yfcd.AmbiguousComparisonException:
                        r_is_history = r0.release_date.prob_lt(d_exchange) > 0.9
                    if r_is_history:
                        prev_r = r0
                        next_r = r1
                if hasattr(prev_r, 'confidence'):
                    do_calc = True
                elif hasattr(next_r, 'confidence'):
                    try:
                        d_exchange < next_r.release_date
                    except yfcd.AmbiguousComparisonException:
                        print("- next release date is estimated, time to recalc:", next_r)
                        do_calc = True
                # print("- releases:") ; pprint(releases)
                # print("- md:") ; pprint(md)
                # raise Exception('review cached release dates')

        if do_calc:
            releases = self._calc_release_dates(period, refresh, check)
            md = {'CalcDate':pd.Timestamp.now()}
            if releases is None:
                yfcm.StoreCacheDatum(self.ticker, cache_key, [], metadata=md)
            else:
                yfcm.StoreCacheDatum(self.ticker, cache_key, releases, metadata=md)
        if releases is None:
            return None

        if not as_df:
            return releases

        period_ends = []
        period_ends_est = []
        release_dates = []
        release_dates_est = []
        delays = []
        for r in releases:
            rpe = r.period_end ; rrd = r.release_date
            if rpe is None or rrd is None:
                print(r)
                raise Exception('Release missing dates')
            period_ends.append(rpe if isinstance(rpe, date) else rpe.date)
            period_ends_est.append(rpe.confidence if isinstance(rpe, yfcd.DateEstimate) else yfcd.Confidence.High)
            dt1 = rpe if isinstance(rpe, date) else rpe.date
            if isinstance(rrd, yfcd.DateRange):
                rrd_range = rrd.end - rrd.start
                release_dates_est.append(yfcd.Confidence.High)
                release_dates.append((rrd.start, rrd.end))
                midpoint = rrd.start + timedelta(days=rrd_range.days//2)
                delays.append(midpoint - dt1)
            elif isinstance(rrd, yfcd.yfcd.DateRangeEstimate):
                release_dates_est.append(rrd.confidence)
                rrd_range = rrd.end - rrd.start
                midpoint = rrd.start + rrd_range*0.5
                if isinstance(midpoint, datetime):
                    midpoint = midpoint.date()
                release_dates.append((rrd.start, rrd.end))
                delays.append(midpoint - dt1)
            else:
                release_dates.append(rrd if isinstance(rrd, date) else rrd.date)
                release_dates_est.append(rrd.confidence if isinstance(rrd, yfcd.DateEstimate) else yfcd.Confidence.High)
                dt2 = rrd if isinstance(rrd, date) else rrd.date
                delays.append(dt2 - dt1)
        df = pd.DataFrame({'Period end':period_ends, 'PE confidence':period_ends_est, 'Release date':release_dates, 'RD confidence':release_dates_est, 'Delay':delays})
        df['Period end'] = pd.to_datetime(df['Period end'])
        df['Period end'] = df['Period end'].dt.tz_localize(self.tzName)
        df = df.set_index('Period end')

        # Set timezone
        # release_dates_formatted = []
        # for i in range(df.shape[0]):
        #     idx = df.index[i]
        #     x = df['Release date'].iloc[i]
        #     if isinstance(x, tuple):
        #         x = (pd.to_datetime(x[0]).tz_localize(self.tzName), pd.to_datetime(x[1]).tz_localize(self.tzName))
        #     else:
        #         x = pd.to_datetime(x).tz_localize(self.tzName)
        #     release_dates_formatted.append(x)
        # df['Release date'] = release_dates_formatted

        return df
```

--------------------------------

### Handle No Release Dates

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_financials_manager.html

Assigns estimated release dates with Low confidence if no actual release dates are provided. Returns the list of releases.

```python
if release_dates is None or len(release_dates) == 0:
            if debug:
                print("No release dates in Yahoo so estimating all with Low confidence")
            for i in range(len(releases)):
                releases[i].release_date = yfcd.DateEstimate(releases[i].period_end+timedelta(days=5)+yfcd.confidence_to_buffer[yfcd.Confidence.Low], yfcd.Confidence.Low)
            return releases
```

--------------------------------

### Get Splits within Date Range (Python)

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

Retrieves stock split data for a given start and optional end date. Ensures date types are strictly checked and handles timezone localization.

```python
yfcu.TypeCheckDateStrict(start, "start")
        if end is not None:
            yfcu.TypeCheckDateStrict(end, "end")

        result = None
        if self.splits is not None and not self.splits.empty:
            start = pd.Timestamp(start).tz_localize(self.splits.index[0].tz)
            if end is not None:
                end = pd.Timestamp(end).tz_localize(self.splits.index[0].tz)
            td_1d = timedelta(days=1)
            if end is None:
                slc = self.splits.loc[start:]
            else:
                slc = self.splits.loc[start:end-td_1d]

            if slc.empty:
                result = None
            else:
                result = slc.copy()

        return result
```

--------------------------------

### Add Releases to Overlap Release Dates (Beginning)

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_financials_manager.html

Ensures the list of releases begins early enough to overlap with the earliest known release dates. Includes an infinite loop safeguard.

```python
release_dates.sort()
        releases.sort()
        ct = 0
        while True:
            try:
                gt_than = releases[0].period_end > release_dates[0]
            except yfcd.AmbiguousComparisonException:
                if hasattr(releases[0].period_end, 'prob_gt'):
                    p = releases[0].period_end.prob_gt(release_dates[0])
                else:
                    p = release_dates[0].prob_lt(releases[0].period_end)
                gt_than = p > 0.9
            if not gt_than:
                break

            ct += 1
            if ct > 100:
                raise Exception("Infinite loop detected while adding release objects")
            prev_period_end = releases[-1].period_end - interval_td
            conf = yfcd.Confidence.High
            if isinstance(prev_period_end, date):
                prev_period_end = yfcd.DateEstimate(prev_period_end, conf)
            else:
                prev_period_end = yfcd.DateEstimate(prev_period_end.date, min(prev_period_end.confidence, conf))

            r = EarningsRelease(interval_td, prev_period_end, None, year_end)

            releases.insert(0, r)
            if debug:
                print("Inserting:", r)
```

--------------------------------

### Get Dividends within a Date Range

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

Retrieves dividend data within a specified date range. If no start or end dates are provided, it returns all available dividend data. Returns None if no data is found.

```python
dividends = events_history.GetDivs(start=date(2023, 1, 1), end=date(2023, 12, 31))
```

--------------------------------

### Processing Daily Raw Data and Adjusting for Stock Splits

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

This snippet demonstrates how to filter daily raw data, calculate expected stock split ratios, and apply adjustments to 'Open', 'Close', and 'Adj Close' prices based on these ratios. It also handles reverse splits.

```python
            # Also get raw daily data from cache
            df_daily_raw = df_daily_raw[df_daily_raw.index.date >= df.index[0].date()]
            #
            f_post = df_daily_raw.index.date > df.index[-1].date()
            df_daily_raw_during = df_daily_raw[~f_post].copy()
            df_daily_raw_during_d = df_daily_raw_during.copy()
            df_daily_raw_during_d.index = df_daily_raw_during_d.index.date ; df_daily_raw_during_d.index.name = "_date"

            if df_daily_post.empty:
                csf_post = 1.0
            else:
                csf_post = yfcu.GetCSF0(df_daily_post)
            expectedRatio = 1.0 / csf_post

            ss_ratio = expectedRatio
            ss_ratioRcp = 1.0 / ss_ratio
            #
            price_data_cols = ["Open", "Close", "Adj Close", "Low", "High"]
            if ss_ratio > 1.01:
                for c in price_data_cols:
                    df[c] *= ss_ratioRcp
                if debug:
                    print("Applying 1:{} stock-split".format(round(ss_ratio, 2)))
            elif ss_ratioRcp > 1.01:
                for c in price_data_cols:
                    df[c] *= ss_ratio
                if debug:
                    print("Applying {.2f}:1 reverse-split-split".format(ss_ratioRcp))
            # Note: volume always returned unadjusted
```

--------------------------------

### get

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

Retrieves historical price data for a given ticker. Users can specify a start and end date, a period, or rely on default caching mechanisms. The function supports various options for data repair, adjustments, and triggering updates.

```APIDOC
## get

### Description
Retrieves historical price data for a given ticker. Users can specify a start and end date, a period, or rely on default caching mechanisms. The function supports various options for data repair, adjustments, and triggering updates.

### Method
GET (Implicit, as it's a data retrieval method)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **start** (datetime or None) - Optional - The start date for the data retrieval. If not provided, 'end' and 'period' must be.
- **end** (datetime or None) - Optional - The end date for the data retrieval. If not provided, 'start' and 'period' must be.
- **period** (string or None) - Optional - A predefined period for data retrieval (e.g., '1d', '5d', '1mo'). If not provided, 'start' and 'end' must be.
- **max_age** (timedelta or None) - Optional - The maximum age of cached data to consider valid. Defaults to 4 hours for daily intervals and 60 hours for weekly intervals.
- **trigger_at_market_close** (boolean) - Optional - If true, triggers data fetching at market close.
- **repair** (boolean) - Optional - If true, attempts to repair missing data.
- **prepost** (boolean) - Optional - If true, includes pre- and post-market data (Note: yfinance-cache does not support this for intraday data).
- **adjust_splits** (boolean) - Optional - If true, adjusts data for stock splits.
- **adjust_divs** (boolean) - Optional - If true, adjusts data for dividends.
- **quiet** (boolean) - Optional - If true, suppresses output messages.

### Request Example
```python
# Example using start and end dates
price_data = yfc_manager.get(start='2023-01-01', end='2023-01-31')

# Example using a period
price_data_period = yfc_manager.get(period='1mo')
```

### Response
#### Success Response (200)
- **DataFrame** - A pandas DataFrame containing the historical price data (Open, High, Low, Close, Volume, Dividends, Stock Splits, etc.) or None if no data is available or an error occurs.

#### Response Example
```json
{
  "Open": [150.0, 151.5, 152.0],
  "High": [152.5, 153.0, 153.5],
  "Low": [149.5, 151.0, 151.5],
  "Close": [151.5, 152.0, 153.0],
  "Volume": [100000, 110000, 105000],
  "Dividends": [0.0, 0.0, 0.0],
  "Stock Splits": [0.0, 0.0, 0.0]
}
```
```

--------------------------------

### Get Exchange Schedule Intervals

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_time.html

Calculates trading intervals for a given exchange, start, and end date. It handles weekly intervals with options to ignore holidays and weekends, and can cache the results. The function prunes future intervals if `exclude_future` is true and the interval is intraday.

```python
elif interval == yfcd.Interval.Week:
        # There is reason for this madness of conditionally igoring holidays & weekends, don't mess with it.
        if week7days:
            week_sched = GetExchangeWeekSchedule(exchange, start, end, ignoreHolidays=False, ignoreWeekends=False, forceStartMonday=True)
            if week_sched is not None:
                if exclude_future:
                    week_sched = week_sched[week_sched["open"] <= dt_now]
                intervals = yfcd.DateIntervalIndex.from_arrays(week_sched.index.left.date, week_sched.index.right.date, closed="left")
        else:
            week_sched = GetExchangeWeekSchedule(exchange, start, end, ignoreHolidays=True, ignoreWeekends=True, forceStartMonday=weekForceStartMonday)
            if week_sched is not None:
                if exclude_future:
                    week_sched = week_sched[week_sched["open"] <= dt_now]
                if discardTimes:
                    intervals = yfcd.DateIntervalIndex.from_arrays(week_sched["open"].dt.date, week_sched["close"].dt.date+td_1d, closed="left")
                else:
                    intervals = pd.IntervalIndex.from_arrays(week_sched["open"], week_sched["close"], closed="left")

    else:
        raise Exception("Need to implement for interval={}".format(interval))

    if cache_key is not None:
        schedIntervalsCache[cache_key] = intervals

    # Only after caching can we prune future intervals
    if exclude_future and intraday:
        intervals = intervals[intervals.left <= dt_now]

    if intervals is not None:
        if isinstance(intervals.left[0], datetime):
            intervals = intervals[(intervals.left >= start_dt) & (intervals.right <= end_dt)]
        if len(intervals) == 0:
            intervals = None

    if debug:
        if intervals is not None:
            yfc_logger.debug(f"GetExchangeScheduleIntervals({istr}) returning interval starts {intervals.left[0]} -> {intervals.left[-1]}")
        else:
            yfc_logger.debug(f"GetExchangeScheduleIntervals({istr}) returning None")
    return intervals
```

--------------------------------

### OptionsManager Class for Cache Options

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_cache_manager.html

Manages application options, loading them from a JSON file and saving changes. It initializes default options if the file is missing or invalid.

```python
class OptionsManager:
    def __init__(self):
        self._initialised = False

    def _load_option(self):
        self._initialised = True  # prevent infinite loop
        d = GetCacheDirpath()
        self.option_file = os.path.join(d, 'options.json')
        try:
            with open(self.option_file, 'r') as file:
                self.options = json.load(file)
        except (FileNotFoundError, json.JSONDecodeError):
            self.options = {}
            # Initialise
            self.__getattr__('max_ages').calendar = '7d'
            self.__getattr__('max_ages').info = '45d'

    def _save_option(self):
        with open(self.option_file, 'w') as file:
            json.dump(self.options, file, indent=4)

    def __getattr__(self, key):
        if not self._initialised:
            self._load_option()

        if key not in self.options:
            self.options[key] = {}
        return NestedOptions(key, self.options[key])

    def __repr__(self):
        if not self._initialised:
            self._load_option()

        return json.dumps(self.options, indent=4)
```

--------------------------------

### Handle Misaligned Weekly Data in yfinance

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

This code block addresses an issue where yfinance might return weekly data not starting on a Monday, despite the fetch start date being aligned. It attempts to re-fetch data by shifting the start date back to ensure the returned data begins on a Monday. If successful, it logs the date range and trims the DataFrame to the requested start date. If alignment fails after multiple attempts, it raises an exception.

```python
        # Check that weekly aligned to Monday. If not, shift start date back and re-fetch
        if self.interval == yfcd.Interval.Week and (not df.empty) and (df.index[0].weekday() != 0):
            # Despite fetch_start aligned to Monday, sometimes Yahoo returns weekly
            # data starting a different day. Shifting back a little fixes
            shift_backs = [2, 4]
            for d in shift_backs:
                fetch_start2 = fetch_start - timedelta(days=d)
                history_args["start"] = fetch_start2
                if debug_yfc:
                    msg = "- weekly data not aligned to Monday, re-fetching from {}".format(fetch_start2)
                    yfcl.TracePrint(msg) if yfcl.IsTracingEnabled() else print(msg)
                df = self.dat.history(**history_args)
                if "Repaired?" not in df.columns:
                    df["Repaired?"] = False
                if self.interval == yfcd.Interval.Week and (df.index[0].weekday() == 0):
                    log_msg = f"requested from YF: {self.istr} {history_args['start']} -> {history_args['end']}"
                    log_msg += f", received: {df.index[0]} -> {df.index[-1]}"
                    self.manager.LogEvent("info", "PriceManager", log_msg)

                    if isinstance(start, datetime):
                        start_dt = start
                    else:
                        start_dt = datetime.combine(start, time(0), self.tz)
                    df = df.loc[start_dt:]
                    break

            if self.interval == yfcd.Interval.Week and (df.index[0].weekday() != 0):
                # print("Date range requested: {} -> {}".format(fetch_start, fetch_end))
                print(df)
                raise Exception("Weekly data returned by YF doesn't begin Monday but {}".format(df.index[0].weekday()))

        if df is not None and df.empty:
            df = None

        if df is None:
            log_msg = "PM::_fetchYfHistory_dateRange() returning None"
        else:
            log_msg = f"PM::_fetchYfHistory_dateRange() returning DF {df.index[0]} -> {df.index[-1]}"
        if yfcl.IsTracingEnabled():
            yfcl.TraceExit(log_msg)
        elif debug_yfc:
            print(log_msg)

        # df = yfcu.CustomNanCheckingDataFrame(df)

        return df
```

--------------------------------

### Determine if Week Starts on Sunday for Specific Exchanges

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_time.html

Checks if the week starts on Sunday, specifically for exchanges like TLV, and considers whether the week has 7 days.

```python
week_starts_sunday = (exchange in ["TLV"]) and (not week7days)
    if debug:
        yfc_logger.debug(f"- week_starts_sunday = {week_starts_sunday}")
```

--------------------------------

### Process Auction Times with Trading Schedule

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_time.html

Maps auction times to trading intervals by flooring relative to market open. This involves calculating an offset and applying it to auction times.

```python
if "auction" in cal.schedule.columns:
            sched = GetExchangeSchedule(exchange, start_d, end_d)
            sched.index = sched.index.date

            # Will map auction time to an interval by flooring relative to market open.
            # Implemented by flooring then applying offset calculated from floored market open.
            intervals_grp = intervals_df.groupby(intervals_df["interval_open"].dt.date)
            # 1 - calculate offset
            res = 'h' if istr.endswith('h') else istr.replace('m', 'T')
            market_opens = intervals_grp.min()["interval_open"]
            if len(market_opens.dt.time.unique()) == 1:
                open0 = market_opens.iloc[0]
                offset = open0 - open0.floor(res)
                auctions_df = sched[["auction"]].copy()
            else:
                market_opens.name = "day_open"
                market_opens.index.name = "day"
                auctions_df = sched[["auction"]].join(market_opens)
                offset = auctions_df["day_open"] - auctions_df["day_open"].dt.floor(res)
            # 2 perform relative flooring:
            if isinstance(offset, pd.Timedelta) and len(auctions_df["auction"].dt.time.unique()) == 1:
                auction0 = auctions_df["auction"].iloc[0]
                auction0_floor = (auction0-offset).floor(res) + offset
                open_offset = auction0_floor - auction0
                auctions_df["auction_open"] = auctions_df["auction"] + open_offset
            else:
                auctions_df["auction_open"] = (auctions_df["auction"]-offset).dt.floor(res) + offset
            auctions_df["auction_close"] = auctions_df["auction"] + yfcd.exchangeAuctionDuration[exchange]
            auctions_df = auctions_df.drop(["day_open", "auction"], axis=1, errors="ignore")
```

--------------------------------

### Aggregating Price Data

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

Aggregates the processed price data (Open, Close, Low, High, Volume) based on the determined grouping column ('Week Start', 'Day Start', or 'intervalID').

```python
            df_new = df_fine.groupby(grp_col).agg(
                Open=("Open", "first"),
                Close=("Close", "last"),
                # AdjClose=("Adj Close", "last"),
                Low=("Low", "min"),
                High=("High", "max"),
                Volume=("Volume", "sum"))
                # CSF=("CSF", "first"),
                # CDF=("CDF", "first"))#.rename(columns={"AdjClose": "Adj Close"})
            if grp_col in ["Week Start", "Day Start"]:
                df_new.index = df_new.index.tz_localize(df_fine.index.tz)
            else:
                df_fine["diff"] = df_fine["intervalID"].diff()
                new_index = np.append([df_fine.index[0]], df_fine.index[df_fine["intervalID"].diff() > 0])
                df_new.index = new_index
```

--------------------------------

### Verify Price Differences with Tolerances

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_utils.html

Compares 'Open', 'Close', 'High', and 'Low' prices, applying a loose tolerance for mismatches where 'Repaired?' states differ. Use for detailed price data validation.

```python
    f_diff_prices = pd.Series(np.full(h.shape[0], False), h.index)
    for c in ["Open", "Close", "High", "Low"]:
        f_close = np.isclose(h[c].to_numpy(), df_yf[c].to_numpy(), rtol)
        f_close = pd.Series(f_close, h.index)
        f_diff_c = ~f_close
        if f_diff_c.any():
            # Use looser tolerance if different 'Repaired?' states
            f_repair_mismatch = np.logical_xor(h["Repaired?"].to_numpy(), df_yf["Repaired?"].to_numpy())
            if f_repair_mismatch.any():
                loose_tol = 0.1
                f_diff_c[f_repair_mismatch] = ~np.isclose(h[c].to_numpy()[f_repair_mismatch], df_yf[c].to_numpy()[f_repair_mismatch], rtol=loose_tol)
        if f_diff_c.any():
            if debug:
                _print_sig_diffs(h, df_yf, c, rtol)
            elif not quiet:
                msg = f"WARNING: {istr}: {np.sum(f_diff_c)}/{n} differences in '{c}'"
                # If very few date(times), append to string
                if not interday and np.sum(f_diff_c) == 1:
                    msg += f" @ {h.index[f_diff_c]}"
                elif interday and np.sum(f_diff_c) < 2:
                    msg += f" @ {h.index.date[f_diff_c]}"
                print(msg)
            f_diff_prices = f_diff_prices | f_diff_c
    prices_bad = f_diff_prices.any()
    f_diff_all = f_diff_all | f_diff_prices
```

--------------------------------

### Initialize PriceHistory Object

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

Initializes the PriceHistory object, setting up parameters for fetching and managing historical price data. Includes type checking for inputs and cache loading.

```python
    def __init__(self, manager, ticker, exchange, tzName, interval, session, proxy, repair=True, contiguous=False):
        if isinstance(interval, str):
            if interval not in yfcd.intervalStrToEnum.keys():
                raise Exception("'interval' if str must be one of: {}".format(yfcd.intervalStrToEnum.keys()))
            interval = yfcd.intervalStrToEnum[interval]
        yfcu.TypeCheckStr(ticker, "ticker")
        yfcu.TypeCheckStr(exchange, "exchange")
        yfcu.TypeCheckStr(tzName, "tzName")
        yfcu.TypeCheckBool(repair, "repair")
        yfcu.TypeCheckBool(contiguous, "contiguous")

        self.manager = manager
        self.ticker = ticker
        self.exchange = exchange
        self.tzName = tzName
        self.interval = interval
        self.session = session
        self.proxy = proxy
        self.repair = repair
        self.contiguous = contiguous

        self.dat = yf.Ticker(self.ticker, session=self.session)
        self.tz = ZoneInfo(self.tzName)

        self.itd = yfcd.intervalToTimedelta[self.interval]
        self.istr = yfcd.intervalToString[self.interval]
        self.interday = self.interval in [yfcd.Interval.Days1, yfcd.Interval.Week]#, yfcd.Interval.Months1, yfcd.Interval.Months3]
        self.intraday = not self.interday
        self.multiday = self.interday and self.interval != yfcd.Interval.Days1

        # Load from cache
        self.cache_key = "history-"+self.istr
        self.h = self._getCachedPrices()
        self._reviewNewDivs()

        # A place to temporarily store new dividends, until prices have
        # been repaired, then they can be sent to EventsHistory

        self._debug = False
        # self._debug = True

        # Manage potential for infinite recursion during price repair:
        self._record_stack_trace = True
        # self._record_stack_trace = False
        self._stack_trace = []
        self._infinite_recursion_detected = False
```

--------------------------------

### Calculate Last Data Timestamp for an Interval

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_time.html

Estimates the last timestamp for which Yahoo Finance might receive data for a given interval, starting from a specified interval start. Handles intraday intervals and exchange schedules.

```python
[docs]
def CalcIntervalLastDataDt(exchange, intervalStart, interval, ignore_breaks=False, yf_lag=None):
    # When does Yahoo stop receiving data for this interval?
    yfcu.TypeCheckStr(exchange, "exchange")
    yfcu.TypeCheckIntervalDt(intervalStart, interval, "intervalStart", strict=False)
    yfcu.TypeCheckInterval(interval, "interval")

    debug = False
    # debug = True

    if debug:
        print(f"CalcIntervalLastDataDt(exchange={exchange}, intervalStart={intervalStart}, interval={interval}, yf_lag={yf_lag})")

    i_td = yfcd.intervalToTimedelta[interval]
    intraday = i_td < timedelta(days=1)
    irange = GetTimestampCurrentInterval(exchange, intervalStart, interval, ignore_breaks=ignore_breaks)
    if irange is None:
        return None
    if debug:
        print("- irange:")
        pprint(irange)

    tz = ZoneInfo(GetExchangeTzName(exchange))
```

--------------------------------

### Initialize EventsHistory

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

Initializes the EventsHistory object, loading cached dividend and split data if available. It requires a manager instance, ticker, exchange, timezone, and proxy.

```python
events_history = EventsHistory(manager=histories_manager, ticker='MSFT', exchange='NASDAQ', tzName='America/New_York', proxy=None)
```

--------------------------------

### Process User Dates and Intervals in yfc_ticker

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_ticker.html

Handles user-provided start and end dates, converting them to datetime objects and adjusting for specific intervals like weekly data which requires Monday starts. It also validates date ranges and determines cache expiration (`max_age`).

```python
start_d = None ; end_d = None
start_dt = None ; end_dt = None
interday = interval in [yfcd.Interval.Days1, yfcd.Interval.Week]#, yfcd.Interval.Months1, yfcd.Interval.Months3]
if start is not None:
    start_dt, start_d = self._process_user_dt(start)
    if start_dt > dt_now:
        return None
    if interval == yfcd.Interval.Week:
        # Note: if start is on weekend then Yahoo can return weekly data starting
        #       on Saturday. This breaks YFC, start must be Monday! So fix here:
        if start_dt is None:
            # Working with simple dates, easy
            if start_d.weekday() in [5, 6]:
                start_d += datetime.timedelta(days=7-start_d.weekday())
        else:
            wd = start_d.weekday()
            if wd in [5, 6]:
                start_d += datetime.timedelta(days=7-wd)
                start_dt = datetime.datetime.combine(start_d, datetime.time(0), tz_exchange)

if end is not None:
    end_dt, end_d = self._process_user_dt(end)

if start_dt is not None and end_dt is not None and start_dt >= end_dt:
    raise ValueError("start must be < end")

if debug_yfc:
    print("- start_dt={} , end_dt={}".format(start_dt, end_dt))

if (start_dt is not None) and start_dt == end_dt:
    return None

if max_age is None:
    if interval == yfcd.Interval.Days1:
        max_age = datetime.timedelta(hours=4)
    elif interval == yfcd.Interval.Week:
        max_age = datetime.timedelta(hours=60)
    # elif interval == yfcd.Interval.Months1:
    #     max_age = datetime.timedelta(days=15)
    # elif interval == yfcd.Interval.Months3:
    #     max_age = datetime.timedelta(days=45)
    else:
        max_age = 0.5*yfcd.intervalToTimedelta[interval]
    if start is not None:
        max_age = min(max_age, dt_now-start_dt)

if period is not None:
    if isinstance(period, (datetime.timedelta, pd.Timedelta)):
        if (dt_now - max_age) < (dt_now - period):
            raise Exception(f"max_age={max_age} must be less than period={period}")
    elif period == yfcd.Period.Ytd:
        dt_now_ex = dt_now.tz_convert(tz_exchange)
        dt_year_start = pd.Timestamp(year=dt_now_ex.year, month=1, day=1).tz_localize(tz_exchange)
        if (dt_now - max_age) < dt_year_start:
            raise Exception(f"max_age={max_age} must be less than days since this year start")
elif start is not None:
    if (dt_now - max_age) < start_dt:
        raise Exception(f"max_age={max_age} must be closer to now than start={start}")

```

--------------------------------

### Fetch Intraday Prices in Batches

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

Fetches intraday stock data in 7-day batches to manage API limits or potential issues with large date ranges. Ensures data is sorted and repaired if necessary.

```python
df_yf = None
                    td_7d = timedelta(days=7)
                    fetch_end_batch = fetch_end
                    fetch_start_batch = fetch_end - td_7d
                    while fetch_end_batch > fetch_start:
                        df_yf_batch = self.dat.history(interval=self.istr, start=fetch_start_batch, end=fetch_end_batch, auto_adjust=False, repair=repair, keepna=True)
                        if "Repaired?" not in df_yf_batch.columns:
                            df_yf_batch["Repaired?"] = False
                        if df_yf is None:
                            df_yf = df_yf_batch
                        else:
                            df_yf = pd.concat([df_yf, df_yf_batch], axis=0)
                        #
                        fetch_end_batch -= td_7d
                        fetch_start_batch -= td_7d
                        fetch_start_batch = max(fetch_start_batch, fetch_start)
                    #
                    df_yf = df_yf.sort_index()
```

--------------------------------

### Fetch Historical Data with Pre/Post Market Handling

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_prices_manager.html

Fetches historical stock data, specifically handling intraday data with pre/post-market information by falling back to direct yfinance fetching when YFC cannot manage it. Includes logic for adjusting 'Close' prices based on 'Adj Close' and selecting relevant columns.

```python
            if prepost and sub_intraday:
                # YFC cannot handle intraday pre- and post-market, so fetch via yfinance
                if debug:
                    # print("- fetching df_fine direct from YF")
                    print(f"- - fetch_start={fetch_start} fetch_end={fetch_end}")
                df_fine_old = self.dat.history(start=fetch_start, end=fetch_end, interval=yfcd.intervalToString[sub_interval], auto_adjust=True, prepost=prepost)
                hist_sub = self.manager.GetHistory(sub_interval)
                if not isinstance(fetch_start, datetime):
                    fetch_start = datetime.combine(fetch_start, time(0), ZoneInfo(self.tzName))
                if not isinstance(fetch_end, datetime):
                    fetch_end = datetime.combine(fetch_end, time(0), ZoneInfo(self.tzName))
                if debug:
                    print("- fetching df_fine via _fetchYfHistory() wrapper")
                    print(f"- - fetch_start={fetch_start} fetch_end={fetch_end}")
                try:
                    df_fine = hist_sub._fetchYfHistory(start=fetch_start, end=fetch_end, prepost=prepost, debug=False, verify_intervals=False, disable_yfc_metadata=True)
                except yfcd.NoPriceDataInRangeException as e:
                    if debug:
                        print("- fetch of fine price data failed:" + str(e))
                    continue
                if df_fine is not None:
                    adj = (df_fine["Adj Close"]/df_fine["Close"]).to_numpy()
                    for c in ["Open", "Low", "High", "Close"]:
                        df_fine[c] *= adj
                    df_fine = df_fine[["Open", "Low", "High", "Close", "Volume", "Dividends", "Stock Splits"]]
                if debug:
                    print("df_fine_old:")
                    print(df_fine_old)
                    print("df_fine:")
                    print(df_fine)
            else:
                if debug:
                    print("- fetching df_fine via YFC")
                hist_sub = self.manager.GetHistory(sub_interval)
                df_fine = hist_sub.get(fetch_start, fetch_end, adjust_splits=False, adjust_divs=False, repair=False, prepost=prepost)
            # df_fine["Adj Close"] = df_fine["Close"] * df_fine["CDF"]
        if debug:
            print("- df_fine:")
            print(df_fine)
        if df_fine is None or len(df_fine) == 0:
            print("YF: WARNING: Cannot reconstruct because Yahoo not returning data in interval")
            if self._record_stack_trace:
                # Pop stack trace
                if len(self._stack_trace) == 0:
                    raise Exception("Failing to correctly push/pop stack trace (is empty too early)")
                if not self._stack_trace[-1] == fn_tuple:
                    for i in range(len(self._stack_trace)):
                        print("  "*i + str(self._stack_trace[i]))
                    raise Exception("Failing to correctly push/pop stack trace (see above)")
                self._stack_trace.pop(len(self._stack_trace) - 1)
            continue
```

--------------------------------

### Logger Retrieval

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_logging.html

Function to get a logger instance for a specific ticker.

```APIDOC
## GetLogger

### Description
Retrieves or creates a logger instance for a given ticker symbol. It sets up a file handler to log events to `events.log` within the ticker's cache directory.

### Parameters
* **tkr** (str) - The ticker symbol for which to get the logger.

### Returns
* **logging.Logger**: The logger instance for the specified ticker.
```

--------------------------------

### Enable yfinance-cache Logging

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_logging.html

Enables logging for yfinance-cache. Accepts logging levels like logging.INFO or logging.DEBUG. Raises an exception for invalid modes.

```python
import logging

# Assuming yfc_logging is imported as such
# from yfinance_cache import yfc_logging

# Example: Enable logging at INFO level
yfc_logging.EnableLogging(logging.INFO)

# Example: Enable logging at DEBUG level
yfc_logging.EnableLogging(logging.DEBUG)

# Example: This would raise an exception
# yfc_logging.EnableLogging(logging.WARNING)
```

--------------------------------

### DateRangeEstimate Addition with Timedelta

Source: https://valueraider.github.io/yfinance-cache/_modules/yfinance_cache/yfc_dat.html

Adds a timedelta to a DateRangeEstimate, shifting both the start and end dates by the timedelta.

```python
def __add__(self, other):
        if isinstance(other, timedelta):
            return DateRangeEstimate(self.start + other, self.end + other, self.confidence)
        raise NotImplementedError(f'Not implemented {self} + {type(other)}={other}')
```
Tokens:
Raw