Python API and docs

[abitrolly]

I could not find any docs on Python API. Are there any helpful methods beyond mere field accessors? For example, I need:

1. Get the size of a substructure
2. Dump or pretty print parsed structure with values from binary file

[KOLANICH]

For pretty-print see #10.
For size of substructure - there is no API - it is computed by compiler for sizeof<type> and sizeof() (and its prereq, lea) is not yet implemented (but something can be done in the mode storing offsets AFTER the parsing is done.

[generalmimon]

For size of substructure - there is no API - it is computed by compiler for sizeof<type> and sizeof() (and its prereq, lea) is not yet implemented (but something can be done in the mode storing offsets).

Well, there actually is an API, if one compiles the spec in --debug mode (Python support for debug mode is a new 0.9 feature introduced in kaitai-io/kaitai_struct_compiler@18cecf4).

You can easily see how this API looks like e.g. by dropping this KSY

meta:
  id: debug_test
  ks-debug: true
seq:
  - id: a
    size: 4
  - id: b
    type: u1

in the devel Web IDE and compiling it for Python. The _read() method for Python will look like

    def _read(self):
        self._debug['a']['start'] = self._io.pos()
        self.a = self._io.read_bytes(4)
        self._debug['a']['end'] = self._io.pos()
        self._debug['b']['start'] = self._io.pos()
        self.b = self._io.read_u1()
        self._debug['b']['end'] = self._io.pos()

which is pretty much self-explanatory. One can get the size of the attribute a by doing struct._debug['a']['end'] - struct._debug['a']['start'] for example.

[KOLANICH]

Yeah, this mode was meant under

the mode storing offsets

AFAIK it is not called `debug` anymore.

[abitrolly]

I thought that https://github.com/kaitai-io/kaitai_struct_visualizer sums up and shows total size as all: value at the bottom. It appeared the bottom numbers are rendering times, not sizes.

As for #10 I would prefer the API to be cross-language with a method name like .dump()

[KOLANICH]

I would prefer the API to be cross-language with a method name like .dump()

[KOLANICH]

s>I would prefer the API to be cross-language with a method name like .dump()

If you named the method dump, it wodn't be possible to create a field or instance with the same name. And it cannot be a separate function in languages without reflection (s.a. C++).

So the method of computing of the repr is language-specific - we don't want to store redundant information.

Also languages usually have well-known conventions for such stuff, and other people code expects everyone to follow them in order to operate as intended, IMHO we should follow them.

[abitrolly]

If you named the method dump, it wodn't be possible to create a field or instance with the same name. And it cannot be a separate function in languages without reflection (s.a. C++).

Then all Python API should be standalone functions exported from runtime?

[KOLANICH]

python api functions in KaitaiStruct class are class/static methods and they are expected to be shadowed by instance methods. What you propose is to add an instance method, and shadowing it would be a problem, so it would have to be called reserved and prohibited to be used in specs (currently it is not implemented, but it is planned).

[dgelessus]

kaitai-io/kaitai_struct#299 discusses supporting each language's native "to string" feature in KS-generated struct classes. Maybe it would make sense to implement dumping/pretty-printing that way? (edit: re-reading @KOLANICH's comments above, I think that's what he was suggesting already.)

If not, there's still no need to worry about name conflicts - just name the method _dump instead of dump. Names starting with underscores are already considered reserved by KS and cannot be used as identifiers in KSYs, so there's no risk of name conflicts.

[abitrolly]

Yep, I would prefer _dump(), because on a typical week it can be a mix of Ruby, Go, JS and Python, and learning new conventions is not something I usually have time.