Builtin Functions¶

Here is a list of all builtin functions the server provides. Some functions that work on code have a table like this in the docstring:

source input	outputs source	region	only single node	allowed types
Yes	No	Mandatory	No	Any

source input: Yes means, that the function expects source code as first argument
outputs source: Yes means that the function returns source code back
region: No means that this function does not accept regions. Optional means that if a region is specified, only the region will be considered. If no region is specified, the whole source is used. Mandatory always requires a region.
only single node: Yes means only a single node on root level is allowed.
allowed types: a list of allowed identifiers on root level. E.g. def means only function definitions are valid.

See reddel_server.red_src(), reddel_server.red_validate().

Basic Functions¶

The following functions are useful for introspection of reddel:

ProviderBase.list_methods(src=None)[source]

Return a list of methods that this Provider exposes to clients

To get more information for each method use reddel_server.ProviderBase.help().

By default this returns all available methods. But it can also be used to only get methods that actually work on a given source. This feature might be handy to dynamically build UIs that adapt to the current context.

To write your own methods that can be filtered in the same way, use the reddel_server.red_validate() decorators.

Parameters:	source (`str`) – if `src` return only compatible methods
Returns:	list of `str`

ProviderBase.help(name)[source]

Return the docstring of the method

Parameters:	name (`str`) – the name of the method.

Example:

import reddel_server
server = reddel_server.Server()
p = reddel_server.ProviderBase(server)
for m in p.list_methods():
    print(m + ":")
    print(p.help(m))

ProviderBase.echo(echo)[source]

Echo the given object

Can be used for simple tests. For example to test if certain values can be send to and received from the server.

Parameters:	echo – the object to echo
Returns:	the given echo

ProviderBase.reddel_version()[source]: Return the reddel version

Some very simple logging control at runtime:

Server.set_logging_level(level)[source]

Set logging level

Parameters:	level (`str` \| `int`) – either `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` or integer
Returns:	None
Raises:	None

Can be called with integer or a string:

>>> import logging
>>> import reddel_server
>>> server = reddel_server.Server()
>>> server.set_logging_level("DEBUG")
>>> server.set_logging_level(logging.INFO)
>>> server.set_logging_level(10)
>>> server.logger.level
10

The string has to be one of the builtin logging levels of logging, see Logging Levels.

Extend the provider at runtime:

ChainedProvider.add_provider(dotted_path)[source]

Add a new provider

Parameters:	dotted_path (`str`) – dotted path to provider class. E.g. `mypkg.mymod.MyProvider`.

This provides a simple plug-in system. A client (e.g. Emacs) can call add_provider with a dotted path to a class within a module. The module has to be importable. So make sure you installed it or added the directory to the PYTHONPATH.

import reddel_server
cp = reddel_server.ChainedProvider(reddel_server.Server())
cp.add_provider('reddel_server.RedBaronProvider')

If the given provider has methods with the same name as the existing ones, it’s methods will take precedence.

This will invalidate the cached methods on this instance and also on the server.

Code Introspection¶

The following functions are useful for inspecting source code:

Any source

RedBaronProvider.analyze(src, *args, **kwargs)[source]

Return the red baron help string for the given source

source input	outputs source	region	only single node	allowed types
Yes	No	No	No	Any

Parameters:	red (`redbaron.RedBaron`) – the red baron source deep (`int`) – how deep the nodes get printed with_formatting (`bool`) – also analyze formatting nodes
Returns:	the help text
Return type:	`str`

Example:

>>> import reddel_server
>>> p = reddel_server.RedBaronProvider(reddel_server.Server())
>>> print(p.analyze("1+1"))
BinaryOperatorNode()
  # identifiers: binary_operator, binary_operator_, binaryoperator, binaryoperatornode
  value='+'
  first ->
    IntNode()
      # identifiers: int, int_, intnode
      value='1'
  second ->
    IntNode()
      # identifiers: int, int_, intnode
      value='1'

RedBaronProvider.get_parents(src, *args, **kwargs)[source]

Return a list of parents (scopes) relative to the given position

source input	outputs source	region	only single node	allowed types
Yes	No	Mandatory	No	Any

Parameters:	red (`redbaron.RedBaron`) – the red baron source start (`reddel_server.Position`) – the start position of the selected region. end (`reddel_server.Position`) – the end position of the selected region.
Returns:	a list of parents starting with the element at position first.
Return type:	`list` of the parents. A parent is represented by a `Parent` of the type, top-left, bottom-right position. Each position is a `Position` object.

>>> import reddel_server
>>> import pprint
>>> p = reddel_server.RedBaronProvider(reddel_server.Server())
>>> src = """def foo(arg1):
...     arg2 = arg2 or ""
...     if Ture:
...         try:
...             pass
...         except:
...             func(subfunc(arg1="asdf"))
... """
>>> pprint.pprint(p.get_parents(src, reddel_server.Position(7, 32), reddel_server.Position(7, 32)))
[Parent(identifier='string', start=Position(row=7, column=31), end=Position(row=7, column=36)),
 Parent(identifier='call_argument', start=..., end=...),
 Parent(identifier='call', start=..., end=...),
 Parent(identifier='call_argument', start=..., end=...),
 Parent(identifier='call', start=..., end=...),
 Parent(identifier='atomtrailers', start=..., end=...),
 Parent(identifier='except', start=..., end=...),
 Parent(identifier='try', start=..., end=...),
 Parent(identifier='ifelseblock', start=..., end=...),
 Parent(identifier='def', start=..., end=...)]

Function Definitions

RedBaronProvider.get_args(src, *args, **kwargs)[source]

Return a list of args and their default value (if any) as source code

source input	outputs source	region	only single node	allowed types
Yes	No	Optional	Yes	def

Parameters:	red (`redbaron.RedBaron`) – the red baron source start (`reddel_server.Position` \| `None`) – the start position of the selected region, if any. end (`reddel_server.Position` \| `None`) – the end position of the selected region, if any.
Returns:	list of argument name and default value.
Return type:	`list` of `tuple` with `str` and `str` \| `None` in it.

The default value is always a string, except for arguments without one which will be represented as None.

>>> import reddel_server
>>> p = reddel_server.RedBaronProvider(reddel_server.Server())
>>> src = """def foo(arg1, arg2, kwarg1=None, kwarg2=1, kwarg3='None'):
...     arg2 = arg2 or ""
...     return arg2 + func(arg1, "arg2 arg2") + kwarg2
... """
>>> p.get_args(src, None, None)
[('arg1', None), ('arg2', None), ('kwarg1', 'None'), ('kwarg2', '1'), ('kwarg3', "'None'")]

Code Transformation¶

The following functions transform source code:

Function Definitions

RedBaronProvider.rename_arg(src, *args, **kwargs)[source]

Rename a argument

source input	outputs source	region	only single node	allowed types
Yes	Yes	Optional	Yes	def

Parameters:	red (`redbaron.RedBaron`) – the red baron source start (`reddel_server.Position` \| `None`) – the start position of the selected region, if any. end (`reddel_server.Position` \| `None`) – the end position of the selected region, if any. oldname (`str`) – name of the argument to rename newname (`str`) – new name for the argument
Returns:	the transformed source code
Return type:	`redbaron.RedBaron`

Example:

>>> import reddel_server
>>> p = reddel_server.RedBaronProvider(reddel_server.Server())
>>> src = """def foo(arg1, arg2, kwarg2=1):  # arg2
...     arg2 = arg2 or ""
...     return arg2 + func(arg1, "arg2 arg2") + kwarg2
... """
>>> print(p.rename_arg(src, None, None, "arg2", "renamed"))
def foo(arg1, renamed, kwarg2=1):  # arg2
    renamed = renamed or ""
    return renamed + func(arg1, "arg2 arg2") + kwarg2

RedBaronProvider.add_arg(src, *args, **kwargs)[source]

Add a argument at the given index

source input	outputs source	region	only single node	allowed types
Yes	Yes	Optional	Yes	Yes

Parameters:	red (`redbaron.RedBaron`) – the red baron source start (`reddel_server.Position` \| `None`) – the start position of the selected region, if any. end (`reddel_server.Position` \| `None`) – the end position of the selected region, if any. index (`int`) – position of the argument. `0` would mean to put the argument in the front. arg (`str`) – the argument to add
Returns:	the transformed source code
Return type:	`redbaron.RedBaron`

Example:

>>> import reddel_server
>>> p = reddel_server.RedBaronProvider(reddel_server.Server())
>>> src = """def foo(arg1, arg2, kwarg2=1):
...     arg2 = arg2 or ""
...     return arg2 + func(arg1, "arg2 arg2") + kwarg2
... """
>>> print(p.add_arg(src, start=None, end=None, index=3, arg="kwarg3=123"))
def foo(arg1, arg2, kwarg2=1, kwarg3=123):
    arg2 = arg2 or ""
    return arg2 + func(arg1, "arg2 arg2") + kwarg2