Split responsibilities to Mode, Method, activate() and activate_using() (v. 0.8.0)

[fohrloop]

This is basically a ticket to myself, and is continuation of work in the PR #51, which left the main branch in an unfinished and bit messy state.

Modes

• Clean up code for Mode. The purpose of Mode is to simply provide the main API and context manager for the user. Everything else should be handled elsewhere. (PR #70)
• Remove creation of DBusAdapter instances from Modes. Pass the DBusAdapter class to a ModeActivationManager -> ModeActivator -> Caller and create an instance of the adapter there (in separate thread) (PR #70)
• Remove prioritization of methods from Modes. Prioritization should be done in ModeActivator. (PR #70)
• Implement Mode.__exit__ and add ModeExit exception which can be used to exit the mode with statement block. (PR #72)
• The callables for Modes like keep.running and keep.presenting should be functions which return instances of Modes. Calling keep.running() should call return a fresh instance of Mode (for supporting running wakepy in multiple threads) (PR #71)
• Create tests for Mode (PR #71)

Deprecated

work done on this ticket but not relevant anymore

• Create a ModeActivationManager class. (PR #76)
  using the queues.

[fohrloop]

I wrote some initial ideas in #75 about renaming ModeActivator to ModeActivationProcess and splitting the responsibilities in three: MethodSelector, MethodPrioritizer and ModeActivator.

I could try to implement the classes next. Modifying the list above to reflect the changes.

[fohrloop]

As mentioned in #100, wakepy Mode activation process will be a blocking operation. This makes it possible to do everything, except heartbeat, in the main thread, which in turn makes things a lot easier. I've already written some documentation to the 0.8.0dev ("main") docs about how this all will work. The plan is roughly:

• Have Mode class as the context manager
• Have activate(methods, ...) function which can activate a "mode" (list of method classes)
• Have activate_using(method, ...) function which may activate a "mode" using a single Method.
• Have Method class for sole purpose of defining subclasses Method
• Have a Heartbeat class which runs a heartbeat in separate thread.

Rough implementation of activate():

def activate(methods: list[MethodCls], ...) -> tuple[ActivationResult, HeartBeat|None]:
    prioritized_methods = prioritize_methods(methods)
    result = ActivationResult()

    for method in prioritized_methods:
        methodresult, heartbeat = activate_using(method, ...)
        result.add(methodresult)
        if result.success:
            break
    return result, heartbeat

• The idea behind activate() function is that you don't need to have Mode instance in order to activate a "mode" defined by a list of Methods.

Rough implementation of activate_using() (pseudocode):

def activate_using(methodcls: MethodCls, ...) -> tuple[MethodUsageResult, HeartBeat|None]:
    method = methodcls()
    if check_platform_support(method) is False:
         return MethodUsageResult(failure_stage=PLATFORM_SUPPORT), None
    if check_requirements(method) is False:
        return MethodUsageResult(failure_stage=REQUIREMENTS), None
    entered = try_enter_mode(method)
    heartbeat_started = try_heartbeat(method)
    if not entered or not heartbeat_started:
        return MethodUsageResult(failure_stage=ACTIVATION), None
    if heartbeat_started:
        heartbeat = Heartbeat(method)
        heartbeat.start()
    return MethodUsageResult(), heartbeat

• The idea behind the activate_using() function is that it should be possible to use a single Method without Modes etc. If there are no other uses, at least it makes the code a bit more modular.
• DbusAdapters etc. should be initialized only once and passed to activate_using, which should accept classes and instances.

New Tasks

• [ ] Create activate function (see below for details) --> Split into Function to activate "mode" with a single Method #107
• [ ] Create activate_using function (see below for details) --> Split into Function to activate mode using a list of methods #108
• [ ] Create Heartbeat class ---> Split into Support for Heartbeat-type of methods #109
• [ ] Split methods of wakepy Method (definitions vs. activation process) --> Split into Function to activate "mode" with a single Method #107

[fohrloop]

The rest of the work on this ticket has been split into multiple tickets. This one is done and can be closed.