Documentation for Tickers.{history,download}() does not match function signature

[pjmcdermott]

Describe bug

The documentation at yfiance.Ticker documentation states that the default for the 'period' parameter for these methods is None.

The actual signature from at least yfinance==0.2.66 is that the default for the period parameter is '1mo'.

There appears to be some recent change around 0.2.66 whereby yfinance is now throwing an error "ValueError: Setting period, start and end is nonsense. Set maximum 2 of them." which draws attention to this discrepancy.

Moreover, as a matter of style I believe it would be better to through an error about "too many parameters" directly at the user entry point, Tickers.{download,history}.

I would also note that the default 'period' parameter for PirceHistory.history() is different from Tickers.{download,history}().

Simple code that reproduces your problem

n/a

Debug log with debug logging enabled

n/a

Bad data proof

No response

yfinance version

0.2.66

Python version

Python 3.12.3

Operating system

Linux larkfield 6.17.0-14-generic #14~24.04.1-Ubuntu SMP PREEMPT_DYNAMIC Thu Jan 15 15:52:10 UTC 2 x86_64 x86_64 x86_64 GNU/Linux

[ValueRaider]

Would presenting the Tickers.history docstring solve like here, and clarifying it depends on start & end being None? https://ranaroussi.github.io/yfinance/reference/yfinance.price_history.html#yfinance.scrapers.history.PriceHistory.history

default 'period' parameter for PirceHistory.history() is different from Tickers.{download,history}().

I don't understand - yf.Tickers('msft aapl goog').history() returns 1 month.

[pjmcdermott]

@ValueRaider I'm not sure I really understand your comment.

My point was that the method documentation does not match the actual signature. It appears that a default of period=None for some methods has changed to period="1mo", but the documentation has not been updated.

I was specifying both the start and end dates in my method calls and assuming the period was set to None, as documented. But with the change in default parameter my method calls were no longer valid. It appears that recently a new error message has been inserted alerting users to this fact which is now causing my method calls to fail.

My key points are:

1. Documentation does not match actual method signatures.
2. I believe it is preferable to raise issues about bad user inputs as high up the calling stack as possible. Currently there are a number of deeper method calls before the warning is issued.
3. There is inconsistency in the default for the period parameter between different methods.

[ValueRaider]

Show the evidence for default 'period' parameter for PirceHistory.history() is different from Tickers.{download,history}(). Everything I test returns 1 month of data default.

[pjmcdermott]

From the code:

    @utils.log_indent_decorator
    def history(self, period=None, interval="1d",
                start=None, end=None, prepost=False, actions=True,
                auto_adjust=True, back_adjust=False, repair=False, keepna=False,
                rounding=False, timeout=10,
                raise_errors=False) -> pd.DataFrame:
        """
        :Parameters:
            period : str
              | Valid periods: 1d,5d,1mo,3mo,6mo,1y,2y,5y,10y,ytd,max
              | Default: 1mo
              | Can combine with start/end e.g. end = start + period

You can see here the default period is set to None, the method documentation below says "Default: 1mo".

[ValueRaider]

Gotcha. Docstring just needs to change to:

Default: 1mo when start & end are None

That can't be implemented in signature hence period=None. If it was period='1mo' then that conflicts with start/end.

[pjmcdermott]

@ValueRaider I fear that you are still not getting my point. The online documentation for Tickers does not mention a default of '1mo' whatsoever.

[ValueRaider]

I understood you first time, I addressed that here #2707 (comment)