Python library should throw specific exceptions

[rossburton]

If I'm parsing an arbitrary file I want to be able to tell "file not found" from "content can't be parsed" from "internal parser error", but this isn't possible if the kaitaistruct read functions (such as ensure_fixed_contents()) just throw Exception().

The module should have a kaitaistruct.ParseException(Exception) class specifically for parse problems.

[GreyCat]

Probably this warrants a long-discussed-but-never-written-down issue about "a better system of exceptions for purpose for format validation" for all languages, but you're right, we should start with something at least. Probably a single error class for languages which feature exceptions would be good. For comparison, current situation with ensure_fixed_contents:

• C++ doesn't throw anything, but rather prints something to std::cout <= definitely not what we'd want
• C# throws Exception
• Go misses ensure_fixed_contents at all
• Java throws KaitaiStream.UnexpectedDataError extends RuntimeException
• JavaScript throws KaitaiStream.UnexpectedDataError
• Lua runs error(...), which is probably equivalent of generic error with a message
• Perl runs die "Unexpected fixed contents [...]", but that's probably nothing we can do about that better
• PHP throws \RuntimeException
• Python throws Exception
• Ruby throws Kaitai::Struct::Stream::UnexpectedDataError

So, Python's situation is not the worst, but not the best either. I propose to start with at least moving all the stuff we could move to the sample UnexpectedDataError implementation (also we should probably decide on exact error message text — it's weirdly different between languages now).

[rossburton]

Good analysis, the Python code is pretty good in comparison! After using my new parser for a while I suggest that the exception used should be defined in the generated code. I was experimenting with a class KaitaiException(Exception) in the Python runtime but that gets ugly quickly as code that is using my generated parser and wants to handle exceptions needs to know that it is generated using Kaitai and import kaitaistruct too. If the generated code wrote an exception class say <Format>UnexpectedDataError, and passed it to kaitaistruct for use when throwing then users of the class don't need to know that kaitai is used at all.

[GreyCat]

Personally, I'm not sure that's a good idea: that would be common "issue" for all languages — if you want to deal with classes specific to KS framework, you'll need to import the framework anyway. The same holds true for KaitaiStream, for example. If you'd want to use it, there's no way around importing it.

Of course, we can either duplicate these runtime libs / exception classes or do something like reexporting:

class FooUnexpectedDataError(UnexpectedDataError):
    pass

But it all seems uglier and more reduntant to me than a single import call anyway.

However, I'm definitely not a person to ask about Python complexities, so let's ask some people who really work with it?

[arekbulski]

Construct has its own exceptions hierarchy: ConstructError is the base, every construct instance throws some derivative of it. @GreyCat If you give me a go, I could add something similar to Python runtime, and then we could port those to other runtimes. I can do C# as well.

You can see the hierarchy in the core module, top of the file:
https://github.com/construct/construct/blob/master/construct/core.py

[GreyCat]

It's not a question of Python, it's a question of inventing a system of exceptions that would be ok for all (or at least most) languages. We can start with Python, but before implementing it we'll need to be sure that all languages would be ok with proposed scheme.

[arekbulski]

I would suggest naming exceptions Kaitai* so they are grouped when typing. Would you prefer so?

[GreyCat]

Namespacing things is done differently in every language. For example, this is probably redundant in Ruby, where everything is already in Kaitai::Struct namespace, or in PHP, where it is in \Kaitai\Struct. Totally ok for most other languages, of course.

[arekbulski]

I think that applies to every language (except brainfuck, if you can call that a programming language at all) including plain C. I am asking how do you want me to proceed when I get to working on exceptions. Do you want me to prefix the names or not?

[GreyCat]

I think that applies to every language.

If "that" is "adding a prefix", then no, it does not, please re-read my reply above.

including plain C.

Which actually does not have any exceptions anyway.

Do you want me to prefix the names or not?

I don't think that prefixing the names has anything to do with "working on exceptions". Prefixes can be added and removed at any time when a need would arise. You'll still have a target-language specific set of exceptions (at least because some languages would use lower_underscore_case and some would use UpperCamelCase), so it's easy to decide on per-language basis, following the general pattern of class naming used in the runtime.

[arekbulski]

I just meant that every language, evan plain old C, seems to have namespaces (not exceptions).

[GreyCat]

I just meant that every language, evan plain old C, seems to have namespaces (not exceptions).

Um, definitely not, and even if a certain language has some namespacing features, it's not always widely used / comfortable enough.

Take Java, for example. Indeed, it has packages and stuff like io.kaitai.struct, but it's a bad idea to name classes like Stream and Struct in that namespace, as it would force people to either have a messy import or use full name like io.kaitai.struct.Stream everywhere.

[arekbulski]

Hmm, good point.