Add harp-python migration guide - #23
Conversation
|
@bruno-f-cruz wouldn't it be better to add this to harp-python instead? If anyone is already starting with pyharp they can just follow the getting started guide and examples and I feel would be cleaner if we didn't have back references. The plan I was considering is to release one last version of harp-python that officially deprecates everything and includes guide and warnings covering all this. |
|
@bruno-f-cruz, I was trying to figure out how to do some of the same things from harp-python, so a migration guide is great! As an aside, I am still playing around with the package, but I was wondering about the difference between accessing the register by address and by name in pyharp: Coming from harp-python, I feel it's a bit clunky where both are accessed in the same way (swapping a string or an int in the same call). Would you consider changing reader.read() to accept a string instead (e.g. reader.read("AnalogData") and then inferring that it's accessing the device module and register class. Sorry, I might have missed a prior discussion regarding this! |
|
We could add yet another overload but I kinda don't like it tbh. The address is an useful overload since it is something that exists in the binary protocol. If you want to use a string it will match the name of the register that you need to pass anyway so not really sure what the gain would be. But try to convince @glopesdev 😆 he may agree with you. |
|
@banchan86 @bruno-f-cruz The advantage of using modules directly is that you have "strings" which are type-safe and discoverable (and faster to type since you don't need quotes and have auto-completion). What I think may be the problem here is that access to the module is circuitous via the Intuitively I would expect the following for consistency: from harp.device import behavior
# passing behavior below would be optional but validate
# that the dataset does match the behavior whoAmI
reader = create_dataset_reader(behavior, "session.harp")
df = reader.read(behavior.AnalogData) |
e6f5fe9 to
a8d3c54
Compare
a8d3c54 to
44d14b5
Compare
44d14b5 to
85f6373
Compare
85f6373 to
fee81da
Compare
open_dataset replaces create_dataset_reader throughout, read takes a register name as well as a class or address, and the epoch example and the parameter table match the current reader: epoch is set once on open_dataset, keep_type keeps its harp-python spelling, and time_index is new, since harp-python inferred the index from the first frame. read_all is gone, so whole-session loading becomes a comprehension over contents, which gains a section of its own. A new section warns that harp-data returns a bitmask register as a single integer column unless demux_bit_masks is set, so a script selecting a flag by name needs it. The static package example imports from the harp.device namespace and names no distribution. Em-dashes, second person and two mid-sentence enumerations are rephrased, and the horizontal rules are removed.
3 participants
This PR adds a short description on how to migrate from the harp-python package to help with the eventual deprecation of that package