casetta/cas.py : new organization, using objets instead of functions

[florian]

As Xion345 said, the organization of cas.py doesn't really follow the object model. A lot of function can be replaced by classes.

With this, some changes can be made in serial.py to improve the code.

Details can be found on the mailing-list:

•  http://listengine.tuxfamily.org/lists.tuxfamily.org/casetta/2007/08/msg00002.html
•  http://listengine.tuxfamily.org/lists.tuxfamily.org/casetta/2007/09/msg00001.html
•  http://listengine.tuxfamily.org/lists.tuxfamily.org/casetta/2007/09/msg00004.html
•  http://listengine.tuxfamily.org/lists.tuxfamily.org/casetta/2007/09/msg00005.html

[florian]

A new branch (transfer-reorg) is open for this work, with code by xion345.

[florian]

(Copy of the Xion345 email on the Casetta mailing-list)

I have just finished to implement the new organization for cas.py described here :  http://dev.filyb.info/casetta/ticket/22. cas.py now uses TransferableObjects? (for example for programs, we have a TransferableProgram? class) Take some coffee because, it is going to be a loooong (but important ! ) email :-P

I defined some guidelines for the creation of such objects:

• Each TransferableObject?, which inherits of all the properties of an object defined in data.py (for example, TransferableProgram? derives from Program) must have a class attribute called header_len (length of a header)
• Moreover, the must have all of the following methods. These methods are called by the functions of devices_serial.py :

• parse_header(header) : This method fills the object's metadata with information from the header and returns the expect length of the object. The expected length of an object (got from the header) is not stored in objects attributes because its real data length may change after.
• checksum_needed(index, data_len) : returns 0 if no checksum if needed as this given index / returns 1 if a checksum should be performed (ie after receiving the sheet of a picture) / returns 2 if we should send 0x06 and ignore if the checksum is valid or not (useful for color screencapture) / returns 3 when index == data_len -1 if you want to do a final checksum, 0 else
• set_raw_data(raw_data) : stores the received raw_data into the object. This method will often contain only the instruction : self.raw_data = raw_data

but it can contain some specials modifications (for screencaptures for example).

• len() : returns the real data length (usually len(self.raw_data)+2)
• build_header() : returns a header for this TransferalbeObject?
• get_raw_data_list() : Returns all data parts which should be transferred. Even if it contains only one element, it must return a list.

If an object is nor supposed to be transferred, it is allowed not to have these last three methods.

See attachments for more details See the transfer-reorg branch in the repository

The reorganization has lots of advantages :

• More in the spirit of Object Orient Programming / More respectful towards the encapsulation principle
• Less data.class instructions which, I think should be avoided
• Less code in devices_serial.py / Cleaner file / More logical organization : devices_serial.py functions only handle the low level communication
• It is now much easier to add support for the transfer of new data types : before it was necessary to modify almost all the functions of cas.py and modify some functions in devices_serial.py. Now you just have to create a class which respects the guidelines mentioned above.

However, it has one drawback. send_data and receive_data functions of devices_serial now manipulate TransferableObjects?. For example the receive_data functions does not return a normal object bu a TransferableObject? (ie receive_data returns a TransferableProgram?). This is not really a problem because all Transferable objects inherits of all the properties of normal Object. However, it is a problem for send_data because it is not able to send a Program (for example) but it can only send a TransferableProgram? (or another TransferableObject?). It is possible to transform a Program into a TransferableProgram?. If prgm is a datacls.Program, you only have to do : prgm = TransferableProgram?(prgm.name,prgm.raw_data,prgm.date,prgm.use_base).

I did not commit that to the SVN repository because it is a VERY big change and I would like to have your approval before. I tested this new cas.py and I was able to send/receive programs,pictures, receive backups(I didn't test backup receipt), receive Screencaptures.

If you have difficulties to sleep, you can read this email twice and I guarantee you will have a good night :-D

[florian]

This change break some part of the code (found thanks pylint):

• Module casetta/fxi.py:
  • E:449:FxdFile.open_file: Module 'cas' has no 'mono_screencapture_to_raw' member
• Module casetta/cas.py:
  • E:424:CasFile.open_file: Undefined variable 'get_data_len'
  • E:436:CasFile.open_file: Undefined variable 'fill_metadata'
  • E:455:CasFile.open_file: Undefined variable 'color_screencapture_to_raw'
  • E:457:CasFile.open_file: Undefined variable 'mono_screencapture_to_raw'
  • W: 51: Unused import errors