The docs for `class int` in functions.rst is missing a section about the possible exceptions it can raise

[ShaharNaveh]

Documentation

The only place there's a mention a possible exception is at

cpython/Doc/library/functions.rst

Lines 1099 to 1105 in 5049eb1

	.. versionchanged:: 3.11
	:class:`int` string inputs and string representations can be limited to
	help avoid denial of service attacks. A :exc:`ValueError` is raised when
	the limit is exceeded while converting a string to an :class:`int` or
	when converting an :class:`int` into a string would exceed the limit.
	See the :ref:`integer string conversion length limitation
	<int_max_str_digits>` documentation.

---

Other classes/functions document their behavior. for example:

cpython/Doc/library/functions.rst

Lines 347 to 348 in 5049eb1

	This function raises :exc:`SyntaxError` or :exc:`ValueError` if the compiled
	source is invalid.

cpython/Doc/library/functions.rst

Lines 424 to 425 in 5049eb1

	For example, ``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` raises
	:exc:`ValueError`.

[picnixz]

We don't document exceptions being raised in general. There can be many exceptions raised and so if users are worried about that, they usually should catch ValueError and TypeError, possibly AttributeError and NotImplementedError.

[picnixz]

For complex it's not the exception being raised that is important, it's the format of the input that is important. Raising ValueError for incorrect inputs is the (default) mode in general, and TypeError when inputs are of incorrect types.

The case for compile leans more towards the exceptional case because it can raise more exceptions than expected (in this case, SyntaxError).

[ShaharNaveh]

@picnixz thanks for the quick reply!

The general gist that I'm getting is that this is intended to not make the document too verbose, and this is not something that was overlooked. If that's the case, please feel free to close the ticket (and sorry for wasting your time)

[picnixz]

No it's fine. I wonder though whether we should actually say what I said somewhere in the docs. I don't know if we say somewhere "In general, ValueError are raised in those cases, AttributeError in those cases, etc". Usually it's good to have a centralized paragraph that tells us. Can you check if this is the case as well?

[ShaharNaveh]

I thought of having some section like this in the docs:

The most common use case where ValueError is raised is when trying to parse an invalid string:

>>> int("not an integer")
ValueError: invalid literal for int() with base 10: 'not an integer'

Under the hood, int() calls the object's __int__ then __index__ methods to convert it to an integer. and any exception raised during that process propagates as-is:

>>> class Intable:
...   def __index__(self):
...     self.no_such
...
>>> int(Intable())
AttributeError: 'Intable' object has no attribute 'no_such'

---

This is a very initial draft. I hope it's enough for you to see my vision for this ticket

[picnixz]

No, what I meant is not having any docs like that in int. It should be an even more generic docs that states that ValueError are raised when the inputs are invalid data (and possibly TypeError). I don't want to document that exceptions are propagated as it's the default behavior and expected behavior.

Otherwise, we'll need to do it for all functions and that's a huge no.

[ShaharNaveh]

No, what I meant is not having any docs like that in int. It should be an even more generic docs that states that ValueError are raised when the inputs are invalid data (and possibly TypeError). I don't want to document that exceptions are propagated as it's the default behavior and expected behavior.

Otherwise, we'll need to do it for all functions and that's a huge no.

oh, so just a line or two that says something like:

will raise `ValueError` if the input data is invalid, `TypeError` if the input type is not supported

?

[picnixz]

Let me be clearer maybe:

• I don't know if there isn't already something in the docs (like in the tutorial, or somewhere else, or on the page about exceptions).
• If there is, I don't think we want to document every possible exception in every possible function. This will make the docs unreadable. We should only document exceptional cases or improve the wording. If we say "input must be a string", then passing anything else and being surprised by a type error is not our problem here as it violates the initial contract.
• If there is no such information, then maybe we should add it but I'm also not sure about this as I don't want it to be considered a hard rule.
• float doesn't say anything about ValueError. It just mentions OverflowError because it's usually an exceptional case.

[ShaharNaveh]

ohhhhh, I'm so stupid 🤦‍♂️

let me check

[ShaharNaveh]

I think that's good enough:

cpython/Doc/library/exceptions.rst

Lines 641 to 644 in 34eca5a

	Passing arguments of the wrong type (e.g. passing a :class:`list` when an
	:class:`int` is expected) should result in a :exc:`TypeError`, but passing
	arguments with the wrong value (e.g. a number outside expected boundaries)
	should result in a :exc:`ValueError`.

Some of the examples at errors.rst are kinda relevant for int() but aren't focusing on it really

---

Although, someone that wants to see which exceptions int() can raise, will check the documentation for int, not for exceptions

[terryjreedy]

I think this can be closed.