ncjishaku as an API

ncjishaku contains numerous internal classes and functions it uses to facilitate both the commands in the cog and miscellaneous parts of bot development.

You can use almost all of these for your own use, but be aware that the internals of ncjishaku, and how they work, are subject to change.

Most of the content in this document is autogenerated.

REPL-related classes and functions

class ncjishaku.repl.scope.Scope(globals_: Dict[str, Any] | None = None, locals_: Dict[str, Any] | None = None)

Class that represents a global and local scope for both scope inspection and creation.

Many REPL functions expect or return this class.

scope = Scope()  # an empty Scope

scope = Scope(globals(), locals())  # a Scope imitating the current, real scope.

scope = Scope({'a': 3})  # a Scope with a pre-existing global scope key, and an empty local scope.

clear_intersection(other_dict: Dict[str, Any])

Clears out locals and globals from this scope where the key-value pair matches with other_dict.

This allows cleanup of temporary variables that may have washed up into this Scope.

Parameters:

other_dict (dict) –

The dictionary to be used to determine scope clearance.

If a key from this dict matches an entry in the globals or locals of this scope, and the value is identical, it is removed from the scope.

Returns:

The updated scope (self).

Return type:

Scope

update(other: Scope)

Updates this scope with the content of another scope.

Parameters:

other (Scope) – The scope to overlay onto this one.

Returns:

The updated scope (self).

Return type:

Scope

update_globals(other: Dict[str, Any])

Updates this scope’s globals with a dict.

Parameters:

other (dict) – The dictionary to be merged into this scope.

Returns:

The updated scope (self).

Return type:

Scope

update_locals(other: Dict[str, Any])

Updates this scope’s locals with a dict.

Parameters:

other (dict) – The dictionary to be merged into this scope.

Returns:

The updated scope (self).

Return type:

Scope

ncjishaku.repl.scope.get_parent_scope_from_var(name: str, global_ok: bool = False, skip_frames: int = 0) → Scope | None

Iterates up the frame stack looking for a frame-scope containing the given variable name.

Returns:

The relevant Scope or None

Return type:

Optional[Scope]

ncjishaku.repl.scope.get_parent_var(name: str, global_ok: bool = False, default: Any = None, skip_frames: int = 0) → Any

Directly gets a variable from a parent frame-scope.

Returns:

The content of the variable found by the given name, or None.

Return type:

Any

class ncjishaku.repl.compilation.AsyncCodeExecutor(code: str, scope: Scope | None = None, arg_dict: Dict[str, Any] | None = None, convertables: Dict[str, str] | None = None, loop: BaseEventLoop | None = None, auto_return: bool = True)

Executes/evaluates Python code inside of an async function or generator.

Example

total = 0

# prints 1, 2 and 3
async for x in AsyncCodeExecutor('yield 1; yield 2; yield 3'):
    total += x
    print(x)

# prints 6
print(total)

create_linecache() → List[str]

Populates the line cache with the current source. Can be performed before printing a traceback to show correct source lines.

property function: Callable[[...], Awaitable[Any] | AsyncGenerator[Any, Any]]

The function object produced from compiling the code. If the code has not been compiled yet, it will be done upon first access.

async for ... in traverse(func: Callable[[...], Awaitable[Any] | AsyncGenerator[Any, Any]]) → AsyncGenerator[Any, Any]

Traverses an async function or generator, yielding each result.

This function is private. The class should be used as an iterator instead of using this method.

class ncjishaku.shell.ShellReader(code: str, timeout: int = 120, loop: AbstractEventLoop | None = None, escape_ansi: bool = True)

A class that passively reads from a shell and buffers results for read.

Example

# reader should be in a with statement to ensure it is properly closed
with ShellReader('echo one; sleep 5; echo two') as reader:
    # prints 'one', then 'two' after 5 seconds
    async for x in reader:
        print(x)

clean_bytes(line: bytes) → str

Cleans a byte sequence of shell directives and decodes it.

property closed: bool

Are both tasks done, indicating there is no more to read?

await executor_wrapper(func: Callable[[Unpack[Ts]], T], *args: Unpack[Ts]) → T

Call wrapper for stream reader.

make_reader_task(stream: IO[bytes], callback: Callable[[bytes], Any])

Create a reader executor task for a stream.

await stderr_handler(line: bytes)

Handler for this class for stderr.

await stdout_handler(line: bytes)

Handler for this class for stdout.

Function-related tools

ncjishaku.functools.executor_function(sync_function: Callable[[P], T]) → Callable[[P], Awaitable[T]]

A decorator that wraps a sync function in an executor, changing it into an async function.

This allows processing functions to be wrapped and used immediately as an async function.

Examples

Pushing processing with the Python Imaging Library into an executor:

from io import BytesIO
from PIL import Image

from ncjishaku.functools import executor_function

@executor_function
def color_processing(color: nextcord.Color):
    with Image.new('RGB', (64, 64), color.to_rgb()) as im:
        buff = BytesIO()
        im.save(buff, 'png')

    buff.seek(0)
    return buff

@bot.command()
async def color(ctx: commands.Context, color: nextcord.Color=None):
    color = color or ctx.author.color
    buff = await color_processing(color=color)

    await ctx.send(file=nextcord.File(fp=buff, filename='color.png'))

Paginator-related tools

class ncjishaku.paginators.PaginatorInterface(bot: Bot | AutoShardedBot, paginator: Paginator, additional_buttons: List[Button[Self]] | None = None, **kwargs: Any)

A message and reaction based interface for paginators.

This allows users to interactively navigate the pages of a Paginator, and supports live output.

An example of how to use this with a standard Paginator:

from nextcord.ext import commands

from ncjishaku.paginators import PaginatorInterface

# In a command somewhere...
    # Paginators need to have a reduced max_size to accommodate the extra text added by the interface.
    paginator = commands.Paginator(max_size=1900)

    # Populate the paginator with some information
    for line in range(100):
        paginator.add_line(f"Line {line + 1}")

    # Create and send the interface.
    # The 'owner' field determines who can interact with this interface. If it's None, anyone can use it.
    interface = PaginatorInterface(ctx.bot, paginator, owner=ctx.author)
    await interface.send_to(ctx)

    # send_to creates a task and returns control flow.
    # It will raise if the interface can't be created, e.g., if there's no reaction permission in the channel.
    # Once the interface has been sent, line additions have to be done asynchronously, so the interface can be updated.
    await interface.add_line("My, the Earth sure is full of things!")

    # You can also check if it's closed using the 'closed' property.
    if not interface.closed:
        await interface.add_line("I'm still here!")

class PageChangeModal(interface: PaginatorInterface, *args: Any, **kwargs: Any)

Modal that prompts users for the page number to change to

await add_line(*args: Any, **kwargs: Any)

A proxy function that allows this PaginatorInterface to remain locked to the last page if it is already on it.

await button_close_callback(interaction: Interaction)

Button to close the interface

button_close_label(_button: Button[Self]) → str

Label for closing the paginator (constant)

await button_current_callback(interaction: Interaction)

Button to refresh the interface

button_current_label(_button: Button[Self]) → str

Current page label (changes on page updates)

button_definitions() → List[Button[Self]]

This is an overridable function you can use to remove buttons or customize their order.

If you only need to add buttons, consider passing additional_buttons to the constructor.

await button_goto_callback(interaction: Interaction)

Button to jump directly to a page

button_goto_label(_button: Button[Self]) → str

Label for selecting a page (constant)

await button_last_callback(interaction: Interaction)

Button to send interface to last page

button_last_label(_button: Button[Self]) → str

Endstop label for going to the last page (changes on page count)

await button_next_callback(interaction: Interaction)

Button to send interface to next page

button_next_label(_button: Button[Self]) → str

Right arrow label for going to the next page (constant)

await button_previous_callback(interaction: Interaction)

Button to send interface to previous page

button_previous_label(_button: Button[Self]) → str

Left arrow label for going to the previous page (constant)

await button_start_callback(interaction: Interaction)

Button to send interface to first page

button_start_label(_button: Button[Self]) → str

Label for returning to the first page (constant)

property closed

Is this interface closed?

property display_page

Returns the current page the paginator interface is on.

await interaction_check(interaction: Interaction)

Check that determines whether this interaction should be honored

property page_count

Returns the page count of the internal paginator.

property page_size: int

A property that returns how large a page is, calculated from the paginator properties.

If this exceeds max_page_size, an exception is raised upon instantiation.

property pages

Returns the paginator’s pages without prematurely closing the active page.

property send_kwargs: Dict[str, Any]

A property that returns the kwargs forwarded to send/edit when updating the page.

As this must be compatible with both nextcord.TextChannel.send and nextcord.Message.edit, it should be a dict containing ‘content’, ‘embed’ or both.

await send_lock_delayed()

A coroutine that returns 1 second after the send lock has been released This helps reduce release spam that hits rate limits quickly

await send_to(destination: Messageable)

Sends a message to the given destination with this interface.

This automatically creates the response task for you.

await wait_loop()

Waits on a loop for updates to the interface. This should not be called manually - it is handled by send_to.

class ncjishaku.paginators.PaginatorEmbedInterface(*args: Any, **kwargs: Any)

A subclass of PaginatorInterface that encloses content in an Embed.

property page_size: int

A property that returns how large a page is, calculated from the paginator properties.

If this exceeds max_page_size, an exception is raised upon instantiation.

property send_kwargs: Dict[str, Any]

A property that returns the kwargs forwarded to send/edit when updating the page.

As this must be compatible with both nextcord.TextChannel.send and nextcord.Message.edit, it should be a dict containing ‘content’, ‘embed’ or both.

class ncjishaku.paginators.FilePaginator(fp: BinaryIO, line_span: Tuple[int, int] | None = None, language_hints: Tuple[str, ...] = (), **kwargs: Any)

A paginator of syntax-highlighted codeblocks, read from a file-like.

Parameters:

• fp – A file-like (implements fp.read) to read the data for this paginator from.

• line_span (Optional[Tuple[int, int]]) – A linespan to read from the file. If None, reads the whole file.

• language_hints (Tuple[str, ...]) – A tuple of strings that may hint to the language of this file. This could include filenames, MIME types, or shebangs. A shebang present in the actual file will always be prioritized over this.

class ncjishaku.paginators.WrappedPaginator(*args: Any, wrap_on: Tuple[str, ...] = ('\n', ' '), include_wrapped: bool = True, force_wrap: bool = False, **kwargs: Any)

A paginator that allows automatic wrapping of lines should they not fit.

This is useful when paginating unpredictable output, as it allows for line splitting on big chunks of data.

Delimiters are prioritized in the order of their tuple.

Parameters:

• wrap_on (tuple) – A tuple of wrapping delimiters.

• include_wrapped (bool) – Whether to include the delimiter at the end of a wrapped line.

• force_wrap (bool) – If this is True, lines will be split at their maximum points should trimming not be possible with any provided delimiter.

add_line(line: str = '', *, empty: bool = False)

Adds a line to the current page.

If the line exceeds the max_size then an exception is raised.

Parameters:

• line (str) – The line to add.

• empty (bool) – Indicates if another empty line should be added.

Raises:

RuntimeError – The line was too big for the current max_size.

Help command classes

These are classes you can use, or subclass yourself, for help commands.

You can use them like this:

from nextcord.ext import commands

from ncjishaku.help_command import MinimalPaginatorHelp

bot = commands.Bot('?', help_command=MinimalPaginatorHelp())

class ncjishaku.help_command.DefaultPaginatorHelp(*args, **kwargs)

A subclass of commands.DefaultHelpCommand that uses a PaginatorInterface for pages.

await send_pages()

A helper utility to send the page output from paginator to the destination.

class ncjishaku.help_command.DefaultEmbedPaginatorHelp(*args, **kwargs)

A subclass of commands.DefaultHelpCommand that uses a PaginatorEmbedInterface for pages.

await send_pages()

A helper utility to send the page output from paginator to the destination.

class ncjishaku.help_command.MinimalPaginatorHelp(*args, **kwargs)

A subclass of commands.MinimalHelpCommand that uses a PaginatorInterface for pages.

await send_pages()

A helper utility to send the page output from paginator to the destination.

class ncjishaku.help_command.MinimalEmbedPaginatorHelp(*args, **kwargs)

A subclass of commands.MinimalHelpCommand that uses a PaginatorEmbedInterface for pages.

await send_pages()

A helper utility to send the page output from paginator to the destination.