Naming bikeshedding thread

[ariebovenberg]

This is an issue to gather bikeshedding discussion about names. To keep churn minimal, any renames will be bundled as much as possible into a small number of releases.

Here are naming discussions. Items are only checked off when a decision has been made.

Comments are welcomed, but note that decisions are not (necessarily) made by majority vote

• add Error suffix to exceptions: SkippedTime -> SkippedTimeError (and others)
• rename py_datetime() to stdlib_datetime(), perhaps adding the to_ prefix?
• Rename local() and instant() to to_local() and to_instant(). The original rationale was the the other to_* methods convert between "aware" types, while conversion to local or instant is more fundamental.
• ...

[JaykeMeijer]

Regarding adding Error to exceptions: This is defined as common practice in the Python docs: https://docs.python.org/3/tutorial/errors.html#user-defined-exceptions, is often mentioned as convention: https://www.geeksforgeeks.org/python-naming-conventions/, https://stackoverflow.com/questions/2903827/why-are-python-exceptions-named-error and is also part of PEP8: https://peps.python.org/pep-0008/#exception-names

I'm not convinced by stdlib_datetime(). Although it covers what it does, stdlib is not a term I'm used to seeing in a Python context and I might think it has something to do with some underlying/referenced C object. Looking at the next item on the list, should it include to_? Would to_datetime be too confusing? Perhaps to_python_datetime, to_standard_datetime or to_native_datetime?

I agree with the renaming of local() and instant()

[spacemanspiff2007]

I think to_local() and to_instant() makes sense because it changes the reference to another reference.

I think for importing/exporting to e.g. datetime another prefix should be used.
How about
create_datetime() or create_py_datetime()
I don't mind the exact naming, I think the important part is that it's possible to differentiate a conversion from a shift of the reference.

[ariebovenberg]

other prefixes that are often used are as_* or into_*, or in_*.

I'm a bit on the fence about mixing different styles of prefix. On the one hand, it can distinguish different 'flavors', but on the other hand, having one prefix is easier to discover. Realistically, most people will just type "to" in their IDE and read the list to see what the possible conversions are. They will just be confused why a different naming convention exists elsewhere.

[ariebovenberg]

@JaykeMeijer Coming back to it, I'm not so sure about the Error suffix for every exception. Some standard modules define exceptions without this suffix. Example the queue module with Empty and Full exceptions. My feeling here is that these exceptions indicate "exceptional" conditions without being "errors" (i.e. invalid state) per se. I feel like SkippedTime falls in the same category. Just like queue.Empty I can imagine this being part of normal control flow:

try:
    my_queue.pop()
except queue.Empty:
    ...

similar to

try:
    local_time.assume_tz("US/Eastern", disambiguate="raise")
except SkippedTime:
    ...

Note that the other exceptions, such as InvalidOffset make more sense to add the Error suffix. This is clearly an "error"—i.e. invalid state.