From a82f1feb3ab2c70cd5cf7083ec433cd77e483f81 Mon Sep 17 00:00:00 2001 From: ShahanaFarooqui Date: Fri, 2 Aug 2024 19:49:25 -0700 Subject: [PATCH] pyln-client: Deprecate category, description and long description from method Category, description and long description from `json_command` and `plugin_command` have been removed in favour of getting them from json schema. Reference PR: Add categories in RPC documentation #7485 Deprecating them in pyln-client as well. They will remove completely in future releases. Changelog-Deprecated: pyln-client: category, description and long descriptions for RPC commands are deprecated now. --- contrib/pyln-client/pyln/client/plugin.py | 43 +++++-------------- .../a-day-in-the-life-of-a-plugin.md | 7 +-- .../json-rpc-passthrough.md | 9 +--- 3 files changed, 15 insertions(+), 44 deletions(-) diff --git a/contrib/pyln-client/pyln/client/plugin.py b/contrib/pyln-client/pyln/client/plugin.py index 1e7116b47..922e6164c 100644 --- a/contrib/pyln-client/pyln/client/plugin.py +++ b/contrib/pyln-client/pyln/client/plugin.py @@ -48,15 +48,11 @@ class Method(object): """ def __init__(self, name: str, func: Callable[..., JSONType], mtype: MethodType = MethodType.RPCMETHOD, - category: str = None, desc: str = None, - long_desc: str = None, deprecated: Union[bool, List[str]] = None): + deprecated: Union[bool, List[str]] = None): self.name = name self.func = func self.mtype = mtype - self.category = category self.background = False - self.desc = desc - self.long_desc = long_desc self.deprecated = deprecated self.before: List[str] = [] self.after: List[str] = [] @@ -327,9 +323,6 @@ class Plugin(object): def add_method(self, name: str, func: Callable[..., Any], background: bool = False, - category: Optional[str] = None, - desc: Optional[str] = None, - long_desc: Optional[str] = None, deprecated: Optional[Union[bool, List[str]]] = None) -> None: """Add a plugin method to the dispatch table. @@ -357,9 +350,6 @@ class Plugin(object): `request.set_result` or `result.set_exception` to return a result or raise an exception for the call. - The `category` argument can be used to specify the category of the - newly created rpc command. - `deprecated` True means that it won't appear unless `allow-deprecated-apis` is true (the default), or if list of version string (e.g. "v23.08"), then start deprecation cycle at that version (and removal after second entry in list). @@ -370,11 +360,7 @@ class Plugin(object): ) # Register the function with the name - method = Method( - name, func, MethodType.RPCMETHOD, category, desc, long_desc, - deprecated - ) - + method = Method(name, func, MethodType.RPCMETHOD, deprecated) method.background = background self.methods[name] = method @@ -497,9 +483,10 @@ class Plugin(object): Internally uses add_method. """ def decorator(f: Callable[..., None]) -> Callable[..., None]: - self.add_method(method_name, f, background=True, category=category, - desc=desc, long_desc=long_desc, - deprecated=deprecated) + for attr, attr_name in [(category, "Category"), (desc, "Description"), (long_desc, "Long description")]: + if attr is not None: + self.log("{} is deprecated but defined in method {}; it will be ignored by Core Lightning".format(attr_name, method_name), level="warn") + self.add_method(method_name, f, background=True, deprecated=deprecated) return f return decorator @@ -512,13 +499,10 @@ class Plugin(object): Internally uses add_method. """ def decorator(f: Callable[..., JSONType]) -> Callable[..., JSONType]: - self.add_method(method_name, - f, - background=False, - category=category, - desc=desc, - long_desc=long_desc, - deprecated=deprecated) + for attr, attr_name in [(category, "Category"), (desc, "Description"), (long_desc, "Long description")]: + if attr is not None: + self.log("{} is deprecated but defined in method {}; it will be ignored by Core Lightning".format(attr_name, method_name), level="warn") + self.add_method(method_name, f, background=False, deprecated=deprecated) return f return decorator @@ -957,13 +941,8 @@ class Plugin(object): methods.append({ 'name': method.name, - 'category': method.category if method.category else "plugin", - 'usage': " ".join(args), - 'description': doc if not method.desc else method.desc + 'usage': " ".join(args) }) - if method.long_desc: - m = methods[len(methods) - 1] - m["long_description"] = method.long_desc manifest = { 'options': list(d.json() for d in self.options.values()), diff --git a/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md b/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md index 6e2a19411..4ca7df890 100644 --- a/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md +++ b/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md @@ -51,14 +51,11 @@ The `getmanifest` method is required for all plugins and will be called on start "rpcmethods": [ { "name": "hello", - "usage": "[name]", - "description": "Returns a personalized greeting for {greeting} (set via options)." + "usage": "[name]" }, { "name": "gettime", "usage": "", - "description": "Returns the current time in {timezone}", - "long_description": "Returns the current time in the timezone that is given as the only parameter.\nThis description may be quite long and is allowed to span multiple lines.", "deprecated": false } ], @@ -101,7 +98,7 @@ The `getmanifest` method is required for all plugins and will be called on start During startup the `options` will be added to the list of command line options that `lightningd` accepts. If any `options` "name" is already taken startup will abort. The above will add a `--greeting` option with a default value of `World` and the specified description. _Notice that currently string, integers, bool, and flag options are supported._ If an option specifies `dynamic`: `true`, then it should allow a `setconfig` call for that option after initialization. -The `rpcmethods` are methods that will be exposed via `lightningd`'s JSON-RPC over Unix-Socket interface, just like the builtin commands. Any parameters given to the JSON-RPC calls will be passed through verbatim. Notice that the `name`, `description` and `usage` fields are mandatory, while the `long_description` can be omitted (it'll be set to `description` if it was not provided). `usage` should surround optional parameter names in `[]`. +The `rpcmethods` are methods that will be exposed via `lightningd`'s JSON-RPC over Unix-Socket interface, just like the builtin commands. Any parameters given to the JSON-RPC calls will be passed through verbatim. Notice that the `name` and `usage` fields are mandatory. `usage` should surround optional parameter names in `[]`. `options` and `rpcmethods` can mark themselves `deprecated: true` if you plan on removing them: this will disable them if the user sets `allow-deprecated-apis` to false, or in `--developer` mode. You can also specify `deprecated` as an array of one or two version numbers, indicating when deprecation starts, and the final version it will be permitted, e.g. `"deprecated": ["v24.02", "v24.02"]`. If only one version number is given, then the final version will be 6 months after the start version. diff --git a/doc/developers-guide/plugin-development/json-rpc-passthrough.md b/doc/developers-guide/plugin-development/json-rpc-passthrough.md index 07d52c104..c25244ff4 100644 --- a/doc/developers-guide/plugin-development/json-rpc-passthrough.md +++ b/doc/developers-guide/plugin-development/json-rpc-passthrough.md @@ -7,9 +7,7 @@ updatedAt: "2023-02-03T08:53:50.840Z" --- Plugins may register their own JSON-RPC methods that are exposed through the JSON-RPC provided by `lightningd`. This provides users with a single interface to interact with, while allowing the addition of custom methods without having to modify the daemon itself. -JSON-RPC methods are registered as part of the `getmanifest` result. Each registered method must provide a `name` and a `description`. An optional `long_description` may also be -provided. This information is then added to the internal dispatch table, and used to return the help text when using `lightning-cli -help`, and the methods can be called using the `name`. +JSON-RPC methods are registered as part of the `getmanifest` result. Each registered method must provide a `name`. This information is then added to the internal dispatch table, and used to return the help text when using `lightning-cli help`, and the methods can be called using the `name`. For example, `getmanifest` result will register two methods, called `hello` and `gettime`: @@ -18,14 +16,11 @@ For example, `getmanifest` result will register two methods, called `hello` and "rpcmethods": [ { "name": "hello", - "usage": "[name]", - "description": "Returns a personalized greeting for {greeting} (set via options)." + "usage": "[name]" }, { "name": "gettime", - "description": "Returns the current time in {timezone}", "usage": "", - "long_description": "Returns the current time in the timezone that is given as the only parameter.\nThis description may be quite long and is allowed to span multiple lines." } ], ...