feat: split huge file synology_api/surveillancestation.py to multiple files

[luboszima]

Is your feature request related to a problem? Please describe.
synology_api/surveillancestation.py file is huge, over 5k lines. Will be better to split it to multiple files by similar logic.

Number of lines

cat synology_api/surveillancestation.py | wc -l
    5731

Number of methods:

 cat synology_api/surveillancestation.py | egrep def | wc -l
     342

Used API endpoints (55):

cat synology_api/surveillancestation.py | egrep 'api_name =' | awk -F'=' '{print $2}' | sort | uniq | tr -d "'"
 SYNO.SurveillanceStation.ActionRule
 SYNO.SurveillanceStation.AddOns
 SYNO.SurveillanceStation.Alert
 SYNO.SurveillanceStation.Alert.Setting
 SYNO.SurveillanceStation.Archiving.Pull
 SYNO.SurveillanceStation.AxisAcsCtrler
 SYNO.SurveillanceStation.AxisAcsCtrler.Search
 SYNO.SurveillanceStation.CMS
 SYNO.SurveillanceStation.CMS.GetDsStatus
 SYNO.SurveillanceStation.CMS.SlavedsList
 SYNO.SurveillanceStation.Camera
 SYNO.SurveillanceStation.Camera.Event
 SYNO.SurveillanceStation.Camera.Group
 SYNO.SurveillanceStation.Camera.Import
 SYNO.SurveillanceStation.Camera.Search
 SYNO.SurveillanceStation.Camera.Status
 SYNO.SurveillanceStation.Camera.Wizard
 SYNO.SurveillanceStation.DigitalOutput
 SYNO.SurveillanceStation.Emap
 SYNO.SurveillanceStation.Emap.Image
 SYNO.SurveillanceStation.ExternalEvent
 SYNO.SurveillanceStation.ExternalRecording
 SYNO.SurveillanceStation.Face
 SYNO.SurveillanceStation.Face.Result
 SYNO.SurveillanceStation.HomeMode
 SYNO.SurveillanceStation.IOModule
 SYNO.SurveillanceStation.IOModule.Search
 SYNO.SurveillanceStation.IVA
 SYNO.SurveillanceStation.IVA.Recording
 SYNO.SurveillanceStation.IVA.Report
 SYNO.SurveillanceStation.IVA.TaskGroup
 SYNO.SurveillanceStation.Info
 SYNO.SurveillanceStation.License
 SYNO.SurveillanceStation.Log
 SYNO.SurveillanceStation.Notification
 SYNO.SurveillanceStation.Notification.Email
 SYNO.SurveillanceStation.Notification.PushService
 SYNO.SurveillanceStation.Notification.SMS
 SYNO.SurveillanceStation.Notification.SMS.ServiceProvider
 SYNO.SurveillanceStation.Notification.Schedule
 SYNO.SurveillanceStation.PTZ
 SYNO.SurveillanceStation.PTZ.Patrol
 SYNO.SurveillanceStation.PTZ.Preset
 SYNO.SurveillanceStation.Recording
 SYNO.SurveillanceStation.Recording.Bookmark
 SYNO.SurveillanceStation.Recording.Export
 SYNO.SurveillanceStation.Recording.Mount
 SYNO.SurveillanceStation.SnapShot
 SYNO.SurveillanceStation.Stream
 SYNO.SurveillanceStation.Transactions.Device
 SYNO.SurveillanceStation.Transactions.Transaction
 SYNO.SurveillanceStation.VisualStation
 SYNO.SurveillanceStation.VisualStation.Layout
 SYNO.SurveillanceStation.VisualStation.Search
 SYNO.SurveillanceStation.YoutubeLive

Describe the solution you'd like
Files can be split by some common logic like group of similar api endpoints (list above)

SYNO.SurveillanceStation.<category>

[luboszima]

FYI: Many methods have a # TODO comment indicating that the method is not working.

[N4S4]

Yeah many methods I couldn't find a way to make them work and didn't have much time to investigate so I marked as TODO. Regarding the splitting I would like to keep it in one file. In which way u would split the files?

[luboszima]

In some of the other PRs/Issues, I started thinking about standardizing the naming of methods #246. This led me to the idea of aligning our structure more closely with Synology API naming conventions.

The main idea is to structure our modules and classes consistently, following a pattern like:

SYNO.<module>.<submodule>.<subsubmodule>?

For example, instead of a monolithic SurveillanceStation class, we can split functionality into submodules and compose them as class attributes.

from .surveillanceStation import Alert  # imported submodule

class SurveillanceStation(base_api.BaseApi):
    def __init__(self):
        self.alert = Alert()

This would allow us to use instance objects in a way similar to the original API classes, like:

surveillanceStation = new SurveillanceStation();
list = surveillanceStation.alert.getList();

Pros:

• Clearer structure and separation of concerns
• Easier testing and maintenance
• More closely aligned with the Synology API hierarchy

Cons:

• Requires significant refactoring, which may impact existing users
  • However, we can provide method aliases for backward compatibility if needed

FYI: @N4S4 @joeperpetua

[joeperpetua]

Regarding the renaming I think @FBoissadier was working on something similar, any thoughts?

[FBoissadier]

Yeah I've started something there is a pull request for the current state of the reorganization.
#259

[N4S4]

I think would be a good idea, it would greatly improve flexibility of the wrapper in general but still keeping old fashion principle for users whom do not want to upgrade their code.

[FBoissadier]

We could make 2 differentes branches and specify it in the readme or we can maintain both solutions in the main like in my pull request but it will be more complexe I think

[luboszima]

We could make 2 differentes branches and specify it in the readme or we can maintain both solutions in the main like in my pull request but it will be more complexe I think

@FBoissadier You can continue with your work, but for old "methods" we can create "aliases".

Example:

# new file
class MyNewClass(base_api.BaseApi):

   def my_new_function(self)
       # magic

### old file
import MyNewClass

class OldClass(base_api.BaseApi):

 old_function = null

  __init__(self, newClass)
    myNewClass = MyNewClass()
    this.old_function=myNewClass.my_new_function()

Like this we can create "aliases" using new method but still keep old names of functions.

[FBoissadier]

Yep that sounds good to have alias

[N4S4]

Yeah I agree too with aliases

[luboszima]

It is important to maintain the same arguments for the old methods, particularly when the new methods have different parameters.

def new_method(paramA: str, paramB: str, paramC: bool = False):
  print(paramA, paramB);
  return paramC;

def old_method(param1: str, param2: str):
  return new_method(paramA=param1, paramB=param2)