mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-02-20 13:54:36 +01:00
Code Issues Projects Releases Wiki Activity

pyln-client: Deprecate category, description and long description from method

Browse source 
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.
This commit is contained in:
ShahanaFarooqui 2024-08-02 19:49:25 -07:00 • committed by Rusty Russell
parent bb400238b1
commit a82f1feb3a
3 changed files with 15 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
contrib/pyln-client/pyln/client/plugin.py
View file

@ -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()),

7
doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md
View file

@ -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.

9
doc/developers-guide/plugin-development/json-rpc-passthrough.md
View file

@ -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."
}
],
...