Errors

[andrewgsavage]

These are pint's errors that I'd expect could be common accross packages

LogarithmicUnitCalculusError(units1: Any, units2: Any | None = None)
Raised on inappropriate operations with logarithmic units.

DimensionalityError(units1: Any, units2: Any, dim1: str = '', dim2: str = '', extra_msg: str = '')
Raised when trying to convert between incompatible units.

OffsetUnitCalculusError(units1: Any, units2: Any | None = None)
Raised on ambiguous operations with offset units.

UndefinedUnitError(unit_names: str | Iterable[str])
Raised when the units are not defined in the unit registry.

[phlptp]

My current library just makes it a nan or error unit since it originates in C++ and used in some contexts where exceptions are not used.
For errors, it seems like there are two basic types of errors

There Unit is undefined or couldn't be constructed for some reason
and a conversion error- an operation on multiple units was incompatible and the results are are an error. From the above comment the first three errors I would consider a conversion error. Not all libraries support generic offsets or even logarithmic units.

[andrewgsavage]

if a library does not support offsets or logarithmic units it can use only the DimensionalityError.

I find distinguishing between the different errors helpful. Seeing ConversionError for 1 degC * 1degC would confuse me as there's no conversion involved.

[neutrinoceros]

I like this on paper: it'd be nice to allow user code to catch unit-related exceptions in a generic fashion, e.g.

from unit_api.exceptions import UndefinedUnitError

try:
    ...
except UndefinedUnitError:
    ...

Unfortunately the only way I know how to implement this would be to make unit_api a runtime dependency to all libraries that wish to support it, and ask them to derive their exception types from ours, which I think is problematic.

For reference, I naively attempted to avoid inheritance using typing.Protocol

from typing import Protocol, runtime_checkable

@runtime_checkable
class UnitConversionError(Exception, Protocol):
    from_unit: str
    to_unit: str

unfortunately this doesn't work:

TypeError: Protocols can only inherit from other protocols, got <class 'Exception'>

It's also not possible to avoid this broken multiple inheritance scheme: trying to drop Exception from parents move the runtime exception to the user code:

TypeError: catching classes that do not inherit from BaseException is not allowed

[seberg]

Unfortunately the only way I know how to implement this would be to make unit_api a runtime dependency to all libraries

Is that actually so bad if it is very lightweight? Maybe it is best to avoid, but then you could use a try/except/else for registration. Or, probably much nicer, an entry-point to register your types with whatever ABCs you want to have in common.

(I am sure you could write an ABC with an overloaded __subclasscheck__ based on some other logic, but registration seems just as well/better to me.)

[lucascolley]

Also, it could be an optional runtime dependency for an experimental mode, while development happens, right? It would only need to be required if we wanted it to work by default, once things are matured. Unless I'm missing something?

[seberg]

Ah, I got it a bit wrong. This is a bigger dance to make sure that import order never matters.
For experimentation, it is probably fine to hard-code known types by implementing __subclasscheck__ via __module__ and __qualname__, I think.
So dunno if it is worthwhile or not. If you go the "give me a namespace" route, it doesn't matter (the namespace owns the type). If you want something that works with anything without such a step in the middle, I suspect the practical route is to just make it work (even if that asks for entry-points).

[neutrinoceros]

Ow, I didn't think of entry points, but I really like the idea !
It makes sense that implementers should explicitly declare support for the API, and this gives them a way to do so without depending on the package they extend at runtime !