[Enhancement] Decorator-based definition of API request methods

[Sartohanix]

Context

The vast majority (all but higher-level wrappers) of methods consist in:

• Parsing input arguments in the form of a json params dictionary
• Updating the params dictionary with API method's name ('method' : ...) and version ('version' : ...)
• Identifying api_path from BaseAPI.gen_list[api_name]['path']
• Returning BaseAPI.request_data(api_name, api_path, params)

Of these steps, only the first one really is unique to each API method. The last three are redundant and could be automatised. Here is a suggestion of improvement based on decorated methods.

Suggestion

Let's consider the following canonical example, from file core_backup.py:

class Backup(base_api.BaseApi):
    """Synology Hyper Backup API."""

    def backup_repository_get(self, task_id: str) -> dict[str, object] | str:
        api_name = 'SYNO.Backup.Repository'
        info = self.gen_list[api_name]
        api_path = info['path']
        req_param = {'version': info['minVersion'],
                     'method': 'get', 'task_id': task_id}

        return self.request_data(api_name, api_path, req_param)

The decorated implementation of method backup_repository_get() would look like:

class Backup(base_api.BaseApi):
    """Synology Hyper Backup API."""

    @api(name='SYNO.Backup.Repository', method='get')
    def backup_repository_get(self, task_id: str) -> dict[str, object]:
        return {'task_id': task_id}

And similarly for other methods. One could imagine cases where the name=<api_name> and method=<method_name> arguments would not need to be provided. Respectively when the static class attribute _API_NAME = '...' is provided and assumed to be the default API name for methods of that class ; and when the name of the python method unambiguously matches the name of the SYNO API method. Here is a possible example from file core_iscsi.py:

class LUN(base_api.BaseApi):
    _API_NAME = "SYNO.Core.ISCSI.LUN"

     # In the @api decorator below,
     #     -> Default api name = self._API_NAME = "SYNO.Core.ISCSI.LUN"
     #     -> Default method name = 'delete'

    @api
    def delete(self, uuid_or_uuids_list: str | Sequence[str]) -> dict:
        return {
            "uuid": '""',
            "uuids": _json(_ensure_list(uuid_or_uuids_list))
        }

Advantages

There are multiple advantages in using such a decorator implementation for API methods:

• Redundant building of meta-arguments for requests in systematised in some common framework (version, api_path). The decorator is defined once and imported in each file.
• Internal api_name used by method is clearly built in the decorator arguments (useful for documentation parsing, where currently an assignment to the variable self.api_name = '...' is enforced)
• The distinction between API-request (decorated) and utility methods (non-decorated) is unambiguous
• The decorator mechanism could be used to register methods in a single common class/object, as suggested in Reorganization of the wrapper by apps #259, at class-import time. For instance, importing the classes from the examples above could dynamically populate a common SYNO or DSM object, leading to possible calls of the API methods through e.g. SYNO.Backup.Repository.get() and SYNO.Core.ISCSI.LUN.delete(). This reconciles the currently implemented approach and the reorganisation of methods per API path suggested in Reorganization of the wrapper by apps #259 ; while maintaining full backward compatibility.

[FBoissadier]

I love this approch!
I never really do my own decorators, but it seems to be a good feature to implement in the "Reorganization" pull request.
I'm kinda curious how you think to implement this?

[Sartohanix]

I think that there are many ways in which this could be done, and I'm not sure yet about the best approach.

Basic decorator implementation

First, for concreteness, here is what the @api decorator (in fact "decorator factory", since @api itself takes arguments) could look like:

from functools import wraps
from typing import Optional, Callable

def api(
    *,  # Keyword arguments only
    name: Optional[str] = None,  # API name (API "path")
    method: Optional[str] = None  # API method name
):
    def decorator(func: Callable):
         # Resolve API method (`method` if provided, else decorated method's name)
         method_name = method if method is not None else func.__name__

        @wraps(func)  # functools `wraps` properly transfers metadata between function and wrapper (e.g. dosctstrings)
        def wrapper(self, *args, **kwargs):
            params = func(self, *args, **kwargs)
            if not params:
                return {}
            
            # Resolve API name (`name` if provided, else method's class `_API_NAME` attribute)
            api_name = name if name is not None else getattr(self, "_API_NAME", None)
            if api_name is None:
                raise AttributeError(
                    "API name not provided and '_API_NAME' not defined on class."
                )
            elif api_name not in self.gen_list:
                raise KeyError(
                    f"'{api_name}' is an invalid Synology API path."
                )

            # Lookup generic API info from inherited BaseAPI.gen_list dict
            info = self.gen_list[api_name]
            api_path = info["path"]

            # Resolve version
            version = kwargs["version"] if "version" in kwargs else info["minVersion"]
            # version = kwargs["version"] if "version" in kwargs else info["maxVersion"]    # Also possible

            # Build `version` and `method` params
            req_param = {
                "version": str(version),
                "method": method_name,
            }
            # Build remaining, method-specific, parameters
            req_param.update({k: v for k, v in params.items() if v is not None})

            # Actual request
            return self.request_data(api_name, api_path, req_param)

        return wrapper

    return decorator

"Registry" mechanism: naive approach

Assuming the final goal is to be able to call each API method from a centralized object, like DSM.Core.XX.YY.method, there are two layers to be implemented. Schematically:

1. Register methods by populating some key/value registry: registry[("<api name>", "<method name">)] = <method>
2. Build a proxy DSM.<API>.<NAME>.<method name> pointing to registry[("<api name>", "<method name">)]

Here I'm giving a simple example only for step 1.. One way could be to have the register being a static attribute of BaseAPI, namely

class BaseAPI:
    _API_REGISTRY = {}
    ...

which gets populated at class definition time, when the decorator factory is called:

from ... import BaseAPI

def api(
    *,  # Keyword arguments only
    name: Optional[str] = None,  # API name (API "path")
    method: Optional[str] = None  # API method name
):
    def decorator(func: Callable):
         # Resolve API method (`method` if provided, else decorated method's name)
         method_name = method if method is not None else func.__name__
        
        @wraps(func)
        def wrapper(self, *args, **kwargs):
            ...
            return self.request_data(api_name, api_path, req_param)

        BaseAPI._API_REGISTRY[(name, method_name)] = wrapper
        return wrapper

    return decorator

Note that in this first approach, name must be provided when decorating the methods. Because at decoration time, one doesn't enter the body of the wrapper function, where we're scanning for default class attribute self._API_NAME.

Here, the registered method could later be called directly from a BaseAPI object, instantiated with proper auth arguments. The self argument of the wrapped methods could be the BaseAPI object itself. This comes with the major caveat that this could only work for subclasses that don't have specific internal mechanisms (specific attributes and helper methods built on top of the BaseAPI inherited layer).

The point I'm trying to make is that we can proceed with some registration mechanism for the methods at class-definition time (when the decorator factory is called).

"Registry" mechanism: more robust approach

A better idea would be to implement python 3.6's special class method __init_subclass__() under BaseAPI. This class method is called each time a class is defined that inherits BaseAPI.

For instance, at decoration time, the methods could simply be flagged (by attaching some metadata) for later processing by BaseAPI's __init_subclass__():

from ... import BaseAPI

def api(
    *,  # Keyword arguments only
    name: Optional[str] = None,  # API name (API "path")
    method: Optional[str] = None  # API method name
):
    def decorator(func: Callable):
         # Resolve API method (`method` if provided, else decorated method's name)
         method_name = method if method is not None else func.__name__

        # Attach metadata, saying "this method was decorated by `@api`, with api name `name` and resolved method `method_name`"
        setattr(func, "_api_data", (name, method_name))
        
        @wraps(func)
        def wrapper(self, *args, **kwargs):
            ...
            return self.request_data(api_name, api_path, req_param)

        return wrapper

    return decorator

Then, under BaseAPI, schematically:

class BaseApi:
    # Shared global registry for all subclasses
    _API_REGISTRY = {}

    def __init_subclass__(cls):

        # Scan class dict for functions tagged by @api(...)
        for func_name, obj in cls.__dict__.items():
            # Look for methods with `_api_data`` attribute
            api_data = getattr(obj, "_api_data", None)
            if api_data is None:
                continue
            
            # Unpack (api_name, method_name)
            api_name, method_name = api_data

            # Override api name = None with classe's `_API_NAME` default
            api_name = api_name or getattr(cls, "_API_NAME", None)
            if not api_name:
                raise AttributeError(
                    f"{cls.__name__}.{func_name} uses @api(...) but no API name is available "
                    f"(set cls._API_NAME or pass name=... to @api)."
                )

            ### POPULATE THE REGISTRY ###
            
            # At this point, we have access to the following data:
            #   - The subclass defining the method: `cls`   (for instance: Backup, Certificate LUN, ...)
            #   - The api name / path: `api_name`     (for instance: SYNO.Backup.Repository, SYNO.Core.Certificate.CRT, SYNO.Core.ISCSI.LUN, ...)
            #   - The api method: `method_name`   (for instance: list, delete, ...)

To be clear, here is schematically the order in which the various methods are executed, from the interpreter's logic when running from synology_api.<module> import <class>:

1. Go through methods definitions. For decorated methods, the api() decorator factory is actually called, and methods are set to its returned value. In this step, the class <class> is still undefined. So, for instance, we can't access its static attributes (like <class>._API_NAME)
2. When all methods have been defined, actually define the <class> class-object.
3. Call BaseAPI.__init_subclass__(<class>)

Should we go for it ?

The above is just the current state of my thoughts on that matter. There are certainly more ways to approach this, and there might be flaws in the above reasoning. Also, I've still not addressed the question of how to define "proxy" calls based on the registry contents (DSM.API.PATH.method()), which certainly comes with its own difficulties (e.g. how/when/whether to actually instantiate BaseAPI's subclasses objects ; how to pass the auth/session information ; ...).

But I guess that with some clever engineering we could arrive at the desired "reorganisation-of-methods-by-api-path" feature, as an additional layer on top of the current implementation (so, no backward compatibility issue whatsoever) ; with no so much additions to the existing code. Maybe the most tedious part would be to go over each method and decorate it. But that process could be done progressively, since, once again, there's no backward compatibility issues / breaking changes from the user-side of things.

Let me know what you think,
Cheers.

[FBoissadier]

Well thanks for theses informations, I need to document myself about this ^^
For instance in my implementation each class can be independant but they all inherit from the BaseApi class, for being able to make something like "DSM.API.PATH.method()" I kinda use a "hack".
For example in the ControlPanel class that inherit from the BaseApi so it initialize the BaseApi class and when you need to use one of the other classes like ApplicationPrivileges I create the class but without calling the init method of it, then share the state of the ControlPanel class to the ApplicationPrivileges class using the self.dict.
It's not the proper way to do it for sure but at least it's working ^^
You can take a look here:
https://github.com/FBoissadier/synology-api/blob/feature/reorganization-by-app/synology_api/DSM/ControlPanel/__init__.py

[Sartohanix]

I understand your approach. It is appealing to clearly/neatly re-package all methods under Synology's API path/endpoint structure. However,

• The whole project structure must be rearranged
• Hence breaking compatibility with current version
• This seems to be an enormous amount of work, probably still taking months before fully operational

In the meantime, here is a suggestion for dynamically generating the API-path routing structure, requiring "minimal" changes to existing code. Everything's currently packed in a modified version of base_api.py:

Modified base_api.py (click to expand)

"""
Base API module for Synology DSM.

Provides a base class for all API implementations, handling authentication,
session management, and connection setup to a Synology NAS device.
"""
from typing import Any, Callable, Optional, Type
from . import auth as syn

from dataclasses import dataclass
from functools import wraps


##########################
# API-method decorators  #
##########################

def api(
    *,  # Keyword arguments only
    name: Optional[str] = None,  # API name (API "path")
    method: Optional[str] = None  # API method name
):
    """
    Decorator (factory) used to declare and wrap a Synology DSM API method.

    This decorator serves two purposes:

    1) Registration:
       It attaches metadata to the decorated function so that
       `BaseApi.__init_subclass__` can discover and register the method
       in the hierarchical API registry. The metadata is stored on the
       function under the `_api_data` attribute.

    2) Execution wrapper:
       It replaces the original method with a wrapper that performs the
       actual HTTP request to the Synology API endpoint when called.

    The decorated method is expected to return a dictionary of
    request parameters specific to the API method. The wrapper then:

    - Resolves the full API name (either from `name` or from the class
      attribute `_API_NAME`),
    - Determines the API version (defaulting to the endpoint's
      minimum version unless explicitly provided),
    - Builds the final request payload,
    - Calls `self.request_data(...)` to execute the request.

    Parameters
    ----------
    name : str, optional
        Fully qualified Synology API name (e.g. "SYNO.Core.ISCSI.LUN").
        If not provided, the class must define a `_API_NAME` attribute.

    method : str, optional
        Synology API method name (e.g. "list", "create").
        If not provided, the Python function name is used.

    Returns
    -------
    Callable
        The wrapped method that performs the HTTP request when invoked.

    Notes
    -----
    - The original function body should only build and return the
      method-specific parameters as a dictionary.
    - The wrapper handles API path resolution, version selection,
      and request execution.
    - The original function metadata (docstring, annotations, name)
      is preserved via `functools.wraps`.
    """

    def decorator(func: Callable):
        # Resolve API method (`method` if provided, else decorated method's name)
        method_name = method if method is not None else func.__name__

        # Attach metadata, saying "this method was decorated by `@api`, with api name `name` and resolved method `method_name`"
        setattr(func, "_api_data", (name, method_name))

        @wraps(func)  # functools `wraps` properly transfers metadata between function and wrapper (e.g. dosctstrings)
        def wrapper(self, *args, **kwargs):
            params = func(self, *args, **kwargs)
            if not params:
                return {}

            # Resolve API name (`name` if provided, else method's class `_API_NAME` attribute)
            api_name = name if name is not None else getattr(self, "_API_NAME", None)
            if api_name is None:
                raise AttributeError(
                    "API name not provided and '_API_NAME' not defined on class."
                )

            # Lookup generic API info from inherited BaseAPI.gen_list dict
            info = self.gen_list[api_name]
            api_path = info["path"]

            # Resolve version
            version = kwargs["version"] if "version" in kwargs else info["minVersion"]
            # version = kwargs["version"] if "version" in kwargs else info["maxVersion"]    # Also possible

            # Build `version` and `method` params
            req_param = {
                "version": str(version),
                "method": method_name,
            }
            # Build remaining, method-specific, parameters
            req_param.update({k: v for k, v in params.items() if v is not None})

            # Actual request
            return self.request_data(api_name, api_path, req_param)

        return wrapper

    return decorator


def register(*, name: Optional[str] = None, method: Optional[str] = None) -> Callable[[Callable], Callable]:
    """
    Decorator that registers an API method by attaching metadata to the function.

    Unlike `api()`, this does not wrap the method and does not change runtime behavior.
    It only sets `func._api_data` for BaseApi.__init_subclass__ to discover.

    Parameters
    ----------
    name : str, optional
        Synology API name/path, e.g. "SYNO.Core.ISCSI.LUN".
        If None, BaseApi.__init_subclass__ should resolve it from cls._API_NAME.
    method : str, optional
        Synology API method name, e.g. "list".
        If None, defaults to the Python function name.

    Returns
    -------
    Callable
        The original function, unchanged.
    """
    def decorator(func: Callable) -> Callable:
        method_name = method if method is not None else func.__name__
        setattr(func, "_api_data", (name, method_name))
        return func

    return decorator


##########################
# API Router definitions #
##########################

@dataclass(frozen=True)
class ApiEntry:
    """
    Immutable record describing one registered API method.

    Instances of this dataclass are created during class creation
    (in BaseApi.__init_subclass__) when a method is discovered as being
    decorated with @api(...) / @register(...).

    Attributes
    ----------
    cls : Type[BaseApi]
        The API wrapper class on which the method is defined (e.g. LUN).
    py_method : str
        The Python method name, as a method of `<cls>`.
    api_name : str
        Full Synology API name, e.g. "SYNO.Core.ISCSI.LUN".
    api_method : str
        Synology API method name to expose on the router, e.g. "list".
    """
    cls: Type['BaseApi']           # e.g. LUN class
    py_method: str  # e.g. "list"
    api_name: str                  # e.g. "SYNO.Core.ISCSI.LUN"
    api_method: str                # e.g. "list"

class RouterNamespace():
    """
    Runtime-generated hierarchical namespace for calling Synology APIs.

    A RouterNamespace instance represents one node in the API "tree" (e.g. SYNO,
    SYNO.Core, SYNO.Core.ISCSI, ...). Child namespaces are attached as attributes,
    and API methods are attached as callables, enabling usage such as:

    ```
        r = api.get_router()
        r.Core.ISCSI.LUN.list(...)
        r.Core.ISCSI.LUN.get(...)
    ```

    Notes
    -----
    - This class is dynamic: attributes are created via setattr().
      This should provide autocompletion for interactive use.
    - Methods are bound exactly once at router construction time. Each method is
      a bound method of an instance of the corresponding wrapper class created
      with BaseApi._from_session(session).
    - The session is stored at class level (RouterNamespace._session) so all
      namespaces share it.
    """
    # Shared session used to create instances for all routed calls.
    _session = None

    # Cache of instantiated API wrapper classes, keyed by wrapper class.
    # Each value is an instance created via BaseApi._from_session(session).
    _class_instances = {}

    def __init__(
        self,
        name: str,
        parent_path: tuple[str, ...],
        registry_in: dict,
        session=None,
    ):
        """
        Create a namespace node and recursively populate it from a registry subtree.

        Parameters
        ----------
        name : str
            Name of this namespace node (e.g. "SYNO", "Core", "ISCSI").
        parent_path : tuple[str, ...]
            Tuple of parent node names; used to compute the full dotted path.
        registry_in : dict
            Registry subtree for this node. Keys are either child namespace names
            or special keys like "_methods".
        session : Authentication, optional
            Synology session object. When provided, it becomes the shared session
            for the entire router tree.
        """
        # Bind the shared session once when constructing the top-level router.
        if session:
            RouterNamespace._session = session

        self._name = name
        self._path = parent_path + (name,)

        # Internal maps used mainly for introspection / debugging.
        # Children and methods are also exposed as real Python attributes
        # via setattr() to improve autocompletion and discoverability.
        self.__children: dict[str, Type['RouterNamespace']] = {}
        self.__methods: dict[str, ApiEntry] = {}

        # Populate this namespace (methods + sub-namespaces) from the registry node.
        self.__populate(registry_in)

    def __bind_api_entry(self, api_entry: ApiEntry):
        """
        Attach one API entry as an attribute on the namespace.

        The attribute name is the Synology API method name (api_entry.api_method),
        and the attribute value is a bound method obtained from a cached class
        instance.

        Notes
        -----
        Binding is performed once at router construction time. The returned bound
        method carries the metadata (docstring, annotations, etc.) of the underlying
        Python method (typically the wrapper produced by @api, which itself should
        preserve original metadata via functools.wraps).
        """
        self.__methods[api_entry.api_method] = api_entry
        setattr(self, api_entry.api_method, self.__get_bound_method(api_entry))

    def __bind_child_namespace(self, namespace):
        """
        Attach a child RouterNamespace as an attribute of this namespace.

        Parameters
        ----------
        namespace : RouterNamespace
            The already-constructed child namespace. It becomes accessible as:
                parent.<child_name>
        """
        self.__children[namespace._name] = namespace
        setattr(self, namespace._name, namespace)

    def __populate(self, node: dict):
        """
        Recursively populate this namespace node from a registry dict.

        The registry format is a nested dict with:
        - "_methods": a set of ApiEntry objects registered at this node
        - other keys: child namespaces whose values are nested registry dicts
        """
        # Bind methods registered at this node.
        for entry in node.get("_methods", ()):
            self.__bind_api_entry(entry)

        # Bind child namespaces.
        for child_name, child_dict in node.items():
            if child_name == "_methods":
                continue
            self.__bind_child_namespace(RouterNamespace(child_name, self._path, child_dict))

    def __get_bound_method(self, entry: ApiEntry) -> Callable[..., Any]:
        """
        Return a bound method for the given ApiEntry.

        This function:
        1) Ensures a wrapper-class instance exists in the class-level cache.
        2) Retrieves the method by name from that instance and returns the bound method.

        Parameters
        ----------
        entry : ApiEntry
            The registry entry describing what wrapper class to instantiate and
            which Python method to retrieve.

        Returns
        -------
        Callable[..., Any]
            A bound method suitable for direct calling from the router namespace.

        Raises
        ------
        RuntimeError
            If the router has no session bound.
        """
        session = RouterNamespace._session
        if session is None:
            raise RuntimeError("Router has no session bound.")

        # Lazily instantiate each wrapper class once per router session.
        if entry.cls not in RouterNamespace._class_instances:
            RouterNamespace._class_instances[entry.cls] = entry.cls._from_session(session)

        # Retrieve the bound method from the cached instance.
        return RouterNamespace._class_instances[entry.cls].__getattribute__(entry.py_method)

    @property
    def _full_name(self) -> str:
        """
        Full dotted name of this namespace node, e.g. "SYNO.Core.ISCSI.LUN".
        """
        return ".".join(self._path)

    @property
    def _children(self) -> tuple:
        """
        Sorted tuple of child namespace names (for introspection/debugging).
        """
        return tuple(sorted(self.__children.keys()))

    @property
    def _methods(self) -> tuple:
        """
        Sorted tuple of method names bound at this namespace (for introspection/debugging).
        """
        return tuple(sorted(self.__methods.keys()))


#################
# BaseApi class #
#################

class BaseApi(object):
    """
    Base class to be used for all API implementations.

    Takes auth and connection information to create a session to the NAS.
    The session is created on instanciation.

    Parameters
    ----------
    ip_address : str
        The IP/DNS address of the NAS.
    port : str
        The port of the NAS. Defaults to `5000`.
    username : str
        The username to use for authentication.
    password : str
        The password to use for authentication.
    secure : bool, optional
        Whether to use HTTPS or not. Defaults to `False`.
    cert_verify : bool, optional
        Whether to verify the SSL certificate or not. Defaults to `False`.
    dsm_version : int, optional
        The DSM version. Defaults to `7`.
    debug : bool, optional
        Whether to print debug messages or not. Defaults to `True`.
    otp_code : str, optional
        The OTP code to use for authentication. Defaults to `None`.
    device_id : str, optional
        Device ID for device binding. Defaults to `None`.
    device_name : str, optional
        Device name for device binding. Defaults to `None`.
    application : str, optional
        The application context for API list retrieval. Defaults to `'Core'`.
    """

    # Class-level attribute to store the shared session
    shared_session: Optional[syn.Authentication] = None

    # Class-level registry of API methods
    _registry = {}

    def __init__(self,
                 ip_address: str,
                 port: str,
                 username: str,
                 password: str,
                 secure: bool = False,
                 cert_verify: bool = False,
                 dsm_version: int = 7,
                 debug: bool = True,
                 otp_code: Optional[str] = None,
                 device_id: Optional[str] = None,
                 device_name: Optional[str] = None,
                 application: str = 'Core',
                 ) -> None:
        """
        Initialize the BaseApi object and create or reuse a session.

        Parameters
        ----------
        ip_address : str
            The IP/DNS address of the NAS.
        port : str
            The port of the NAS.
        username : str
            The username to use for authentication.
        password : str
            The password to use for authentication.
        secure : bool, optional
            Whether to use HTTPS or not. Defaults to `False`.
        cert_verify : bool, optional
            Whether to verify the SSL certificate or not. Defaults to `False`.
        dsm_version : int, optional
            The DSM version. Defaults to `7`.
        debug : bool, optional
            Whether to print debug messages or not. Defaults to `True`.
        otp_code : str, optional
            The OTP code to use for authentication. Defaults to `None`.
        device_id : str, optional
            Device ID for device binding. Defaults to `None`.
        device_name : str, optional
            Device name for device binding. Defaults to `None`.
        application : str, optional
            The application context for API list retrieval. Defaults to `'Core'`.

        Returns
        -------
        None
            Just actions, no return values.
        """
        self.application = application

        # Reuse shared session if it exists, otherwise create a new one
        if BaseApi.shared_session:
            self.session = BaseApi.shared_session
        else:
            if not all([ip_address, port, username, password]):
                raise ValueError(
                    "Missing required credentials for initial authentication.")

            self.session = syn.Authentication(
                ip_address, port, username, password, secure, cert_verify, dsm_version, debug, otp_code,
                device_id, device_name
            )
            self.session.login()
            self.session.get_api_list(self.application)
            self.session.get_api_list()

            # Store the new session in the shared class-level attribute
            BaseApi.shared_session = self.session

        # Initialize other attributes from the session
        self.request_data: Any = self.session.request_data
        self.batch_request = self.session.request_multi_datas
        self.core_list: Any = self.session.app_api_list
        self.gen_list: Any = self.session.full_api_list
        self._sid: str = self.session.sid
        self.base_url: str = self.session.base_url

    def logout(self) -> None:
        """
        Close current session.

        Returns
        -------
        None
            Action, no return values.
        """
        if self.session:
            self.session.logout()
            if BaseApi.shared_session == self.session:
                BaseApi.shared_session = None
        return


    ####################################
    # Additionnal code for API routing #
    ####################################

    @classmethod
    def _from_session(cls, session: syn.Authentication, *, application: str = "Core",
                      init_kwargs: Optional[dict] = None) -> "BaseApi":
        """
        Create an instance without performing login, using an existing session.

        This is used by RouterNamespace to create lightweight "call-capable"
        instances of API wrapper subclasses (LUN, Target, ...), all sharing the
        same authenticated session.

        Notes
        -----
        - The instance is created via `cls.__new__` to bypass `__init__`.
        - Attributes that BaseApi normally copies from the session in `__init__`
          are mirrored here.
        - `init_kwargs` is reserved for future use if some subclasses require
          additional initialization parameters.

        Parameters
        ----------
        session : syn.Authentication
            Existing authenticated session.
        application : str, optional
            Application context for API list retrieval. Defaults to "Core".
        init_kwargs : dict, optional
            Placeholder for future subclass-specific initialization parameters.

        Returns
        -------
        BaseApi
            A new instance of `cls` bound to the provided session.
        """

        # TODO: Handle init kwargs for the subclasses requiring it.

        obj = cls.__new__(cls)
        obj.application = application
        obj.session = session

        # Mirror what BaseApi.__init__() sets from session
        obj.request_data = session.request_data
        obj.batch_request = session.request_multi_datas
        obj.core_list = session.app_api_list
        obj.gen_list = session.full_api_list
        obj._sid = session.sid
        obj.base_url = session.base_url

        return obj

    def __init_subclass__(cls):
        """
        Hook executed when a subclass of `BaseApi` is defined.

        This scans the subclass dictionary for callables annotated with
        metadata (e.g. via `@api` or `@register`) and stores them in a hierarchical
        registry structure (`BaseApi._registry`).

        Registry structure
        ------------------
        `BaseApi._registry` is a nested dictionary representing the dot-separated
        Synology API namespace. For example, an API name:
        ```
            SYNO.Core.ISCSI.LUN
        ```

        will correspond to the nested path:
        ```
            _registry["Core"]["ISCSI"]["LUN"]
        ```
        Each node may contain:
        - `"_methods"`: a `set[ApiEntry]` registered at that node
        - other keys: child namespace nodes
        - `"_endpoints"`: a `set[str]` stored at the root only, used for later
          validation against the Synology API list.

        Raises
        ------
        AttributeError
            If a registered method provides no API name and the class does not
            define `_API_NAME`.
        ValueError
            If the API name does not start with the `"SYNO"` root.
        """
        print(f"Defining class {cls.__name__} ...")
        # Scan class dict for functions tagged by @api(...)
        for func_name, obj in cls.__dict__.items():
            # Look for methods with `_api_data`` attribute
            api_data = getattr(obj, "_api_data", None)
            if api_data is None:
                continue

            # Unpack (api_name, method_name)
            api_name, method_name = api_data

            # Override api name = None with classe's `_API_NAME` default
            api_name = api_name or getattr(cls, "_API_NAME", None)
            if not api_name:
                raise AttributeError(
                    f"{cls.__name__}.{func_name} uses @api(...) but no API name is available "
                    f"(set cls._API_NAME or pass name=... to @api)."
                )

            # Split API endpoint path in its components
            api_endpoint_path = api_name.split('.')
            if api_endpoint_path[0] == 'SYNO':
                api_endpoint_path = api_endpoint_path[1:]
            else:
                raise ValueError(f"API endpoint root must be 'SYNO', in '{api_name}'")

            # At the root of the registry, store all API endpoints for later
            # explicit checking that those are actually valid Synology API paths
            if '_endpoints' not in BaseApi._registry:
                BaseApi._registry['_endpoints'] = set()

            BaseApi._registry['_endpoints'].add(api_name)

            # Populate the registry hierarchically
            current_registry_node = BaseApi._registry
            for path_node in api_endpoint_path:
                if path_node not in current_registry_node:
                    current_registry_node[path_node] = {}
                current_registry_node = current_registry_node[path_node]

            # Deepest node reached, now populate methods
            if '_methods' not in current_registry_node:
                current_registry_node['_methods'] = set()

            # Dataclass containing info about the method
            current_registry_node['_methods'].add(
                ApiEntry(
                    cls=cls,
                    py_method=func_name,
                    api_name=api_name,
                    api_method=method_name
                )
            )

            print(f"Found api method: {(api_name, method_name)} in {cls}.{func_name}")

    def get_router(self) -> RouterNamespace:
        """
        Build and return a RouterNamespace object rooted at `"SYNO"`.

        This validates that all registered API endpoints exist in the Synology
        API list previously fetched during authentication, then constructs the
        router tree by recursively walking `BaseApi._registry`.

        Returns
        -------
        RouterNamespace
            Root namespace object. Child namespaces and methods are exposed
            as attributes.

        Notes
        -----
        - This requires that a session exists (i.e. `BaseApi.__init__` has logged in).
        - Endpoint validation uses the Synology API list stored on `self.gen_list`.
        - The special registry key `"_endpoints"` is removed from the registry after
          validation.
        """
        # Check session exists
        if not BaseApi.shared_session:
            print("API Router object can only be created after login.")
            return

        # Validate all registered API endpoints once ; removing key from registry
        invalid_endpoints = BaseApi._registry.pop('_endpoints') - self.gen_list.keys()
        if invalid_endpoints:
            print("Error: Invalid API endpoints appear to have been registered: ")
            print(invalid_endpoints)
            return

        return RouterNamespace('SYNO', (), BaseApi._registry, session=BaseApi.shared_session)

Two decorators are implemented.

• The first one, @api, would require adapting each method in such a way that only the params json dictionary is returned by the method ; the call to BaseApi.request_data() being automatically handled.
• The second one, @register, can be added to any method making an API call in its current form. It only handles the registration of methods for dynamic generation of the hierarchical API "router".

Take this example from core_package.py:

class Package(base_api.BaseApi):

    def list_installed(self, additional: list = [], ignore_hidden: bool = False) -> dict:
        api_name = 'SYNO.Core.Package'
        info = self.core_list[api_name]
        api_path = info['path']
        req_param = {
            "method": "list",
            "version": info['maxVersion'],
            "ignore_hidden": ignore_hidden,
            "additional": json.dumps(additional)
        }
        return self.request_data(api_name, api_path, req_param)

Simply add the decorator @register to the method:

from .base_api import register

class Package(base_api.BaseApi):

    @register(name='SYNO.Core.Package', method='list')
    def list_installed(self, additional: list = [], ignore_hidden: bool = False) -> dict:
        api_name = 'SYNO.Core.Package'
        info = self.core_list[api_name]
        api_path = info['path']
        req_param = {
            "method": "list",
            "version": info['maxVersion'],
            "ignore_hidden": ignore_hidden,
            "additional": json.dumps(additional)
        }
        return self.request_data(api_name, api_path, req_param)

Now, that method can be invoked from the dynamically generated router class:

from synology_api.base_api import BaseApi

api = BaseApi(
    ip_address='my.nas.com',
    port='5001',
    username='myuser',
    password='mypassword',
    secure=True,
    cert_verify=True
)

router = api.get_router()

package_list = router.Core.Package.list()

print(package_list)

For a given router "node", the available sub-APIs and methods can be listed using

print(router.Core._children)  # List of child API nodes
print(router.Core.Package._methods)  # List of available methods for that node

Finally, note that an @api-decorated implementation of the above method (instead of @register) would take the simple, more compact form:

from .base_api import register

class Package(base_api.BaseApi):

    @api(name='SYNO.Core.Package', method='list')
    def list_installed(self, additional: list = [], ignore_hidden: bool = False) -> dict:
        return {
            "ignore_hidden": ignore_hidden,
            "additional": json.dumps(additional)
        }

---

This could be a compromise / temporary solution to have the method calls implemented per API path, with minimal additions to the current code, and without breaking compatibility.
Still, it would remain to decorate under every class each method that should appear under the router object, and possibly using the @api decorator which requires returning the parameters dictionary instead of making the actual call to self.request_data().

Is it worth the effort ? Arguably, but anyway I like the idea.

[FBoissadier]

Thanks for those infos, I will check this weekend about what you share here to use it and tests it from my side :)
From my PoV it seems to be a good thing to do, for the implementation maybe we can do it pretty same way that I'm implementing the current reoganization, on a separate folder in a fork?