polytracker.plugins

A module containing base classes for implementing PolyTracker plugins and commands.

For extending the REPL, see polytracker.repl.

Examples

Let’s say you want to implement a new command called foo that can be executed at the command line by running

$ polytracker foo

All you have to do is extend Command:

class Foo(Command):
    name = "foo"
    help = "This is the foo command!"

    def run(self, args: Namespace):
        print("Inside foo!")
        return 0

Simply extending the Command class will automatically register the command.

$ polytracker foo --help
usage: polytracker foo [-h]

optional arguments:
  -h, --help  show this help message and exit
$ polytracker foo
Inside foo!

To add additional command line arguments, extend the Command.__init_arguments__() function:

class Foo(Command):
    name = "foo"
    help = "This is the foo command!"

    def __init_arguments__(parser: ArgumentParser):
        parser.add_argument("--bar", type=str, help="baz")

    def run(self, args: Namespace):
        print(f"Inside foo: {bar!r}")
        return 0

$ polytracker foo --bar baz
Inside foo: "baz"

Next, say you want to add a subcommand to foo called asdf:

$ polytracker foo asdf
Do something completely different!

You can do this by subclassing Subcommand:

class ASDF(Subcommand[Foo]):
    name = "asdf"
    help = "a subcommand of foo"
    parent_type = Foo

    def __init_arguments__(self, parser):
        parser.add_argument("QWERTY", type=str, help="another argument")

    def run(self, args: Namespace):
        print("Inside ASDF: {args.QWERTY!r}")

The idea behind subcommands is that they allow you to programmatically extend any existing command without having to edit the code in which the parent command is implemented.

plugins classes

AbstractCommand

class polytracker.plugins.AbstractCommand(argument_parser: ArgumentParser, parent: Plugin | None = None)

Bases: Plugin

Abstract base class for PolyTracker commands.

A PolyTracker command is exposed as a command line option.

__init__(argument_parser: ArgumentParser, parent: Plugin | None = None)

__init_arguments__(parser: ArgumentParser)

Initializes this command’s argument parser.

Subclasses should extend this function and add any necessary options to parser.

extension_types: List[Type[CommandExtension]] | None = None: An auto-populated list of eny extensions to this command.

property full_name: str

help: str: Help string for this command.

name: str: The name of this plugin.

parent: Plugin | None: The parent of this plugin, if it is a sub-plugin.

parent_parsers: Tuple[ArgumentParser, ...] = (): An optional sequence of parent argument parsers from which to parse options.

abstract run(args: Namespace)

Callback for when the command is run.

Parameters:: args – The result of parsing the commandline arguments set up by Command.__init_arguments__().

subcommand_types: List[Type[Subcommand]] | None = None: An auto-populated list of subcommands of this command.

subparser: Any | None = None: A subparser, auto-populated if subcommand_types is not None.

Command

class polytracker.plugins.Command(argument_parser: ArgumentParser)

Bases: AbstractCommand, ABC

A base command class.

__init__(argument_parser: ArgumentParser)

__init_arguments__(parser: ArgumentParser)

Initializes this command’s argument parser.

Subclasses should extend this function and add any necessary options to parser.

extension_types: List[Type[CommandExtension]] | None = None: An auto-populated list of eny extensions to this command.

extensions: List[CommandExtension]

property full_name: str

help: str: Help string for this command.

name: str: The name of this plugin.

parent: Plugin | None: The parent of this plugin, if it is a sub-plugin.

parent_parsers: Tuple[ArgumentParser, ...] = (): An optional sequence of parent argument parsers from which to parse options.

abstract run(args: Namespace)

Callback for when the command is run.

Parameters:: args – The result of parsing the commandline arguments set up by Command.__init_arguments__().

subcommand_types: List[Type[Subcommand]] | None = None: An auto-populated list of subcommands of this command.

subcommands: List[Subcommand]

subparser: Any | None = None: A subparser, auto-populated if subcommand_types is not None.

CommandExtension

class polytracker.plugins.CommandExtension(parent: Plugin | None = None)

Bases: Plugin, Generic[C], ABC

__init__(parent: Plugin | None = None)

property full_name: str

name: str: The name of this plugin.

parent: Plugin | None: The parent of this plugin, if it is a sub-plugin.

property parent_command: C: Returns the parent command associated with this extension

parent_parsers: Tuple[ArgumentParser, ...] = ()

abstract run(command: C, args: Namespace)

CommandExtensionMeta

class polytracker.plugins.CommandExtensionMeta(name, bases, namespace, /, **kwargs)

Bases: PluginMeta, Generic[C]

A metaclass for command extensions.

__init__(name, bases, clsdict)

__instancecheck__(instance): Override for isinstance(instance, cls).

__subclasscheck__(subclass): Override for issubclass(subclass, cls).

_abc_caches_clear(): Clear the caches (for debugging or testing).

_abc_registry_clear(): Clear the registry (for debugging or testing).

_dump_registry(file=None): Debug helper to print the ABC registry.

mro(): Return a type’s method resolution order.

property parent_command_type: Type[C]: Returns the type of this command extension’s parent command.

parent_type: Type[Plugin] | None = None: The type of this plugin’s parent plugin, in the case of sub-plugins.

register(subclass)

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

Plugin

class polytracker.plugins.Plugin(parent: Plugin | None = None)

Bases: ABC

Abstract base class for all PolyTracker plugins.

At a minimum, a plugin must define a unique name class member.

__init__(parent: Plugin | None = None)

property full_name: str

name: str: The name of this plugin.

parent: Plugin | None: The parent of this plugin, if it is a sub-plugin.

PluginMeta

class polytracker.plugins.PluginMeta(name, bases, namespace, /, **kwargs)

Bases: ABCMeta

Metaclass for PolyTracker plugins.

__init__(name, bases, clsdict)

__instancecheck__(instance): Override for isinstance(instance, cls).

__subclasscheck__(subclass): Override for issubclass(subclass, cls).

_abc_caches_clear(): Clear the caches (for debugging or testing).

_abc_registry_clear(): Clear the registry (for debugging or testing).

_dump_registry(file=None): Debug helper to print the ABC registry.

mro(): Return a type’s method resolution order.

parent_type: Type[Plugin] | None = None: The type of this plugin’s parent plugin, in the case of sub-plugins.

register(subclass)

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

Subcommand

class polytracker.plugins.Subcommand(argument_parser: ArgumentParser, parent: Plugin | None = None)

Bases: Generic[C], AbstractCommand, ABC

An abstract class for PolyTracker subcommands.

__init__(argument_parser: ArgumentParser, parent: Plugin | None = None)

__init_arguments__(parser: ArgumentParser)

Initializes this command’s argument parser.

Subclasses should extend this function and add any necessary options to parser.

extension_types: List[Type[CommandExtension]] | None = None: An auto-populated list of eny extensions to this command.

extensions: List[CommandExtension]

property full_name: str

help: str: Help string for this command.

name: str: The name of this plugin.

parent: Plugin | None: The parent of this plugin, if it is a sub-plugin.

property parent_command: C: Returns the parent command associated with this subcommand.

parent_parsers: Tuple[ArgumentParser, ...] = (): An optional sequence of parent argument parsers from which to parse options.

abstract run(args: Namespace)

Callback for when the command is run.

Parameters:: args – The result of parsing the commandline arguments set up by Command.__init_arguments__().

subcommand_types: List[Type[Subcommand]] | None = None: An auto-populated list of subcommands of this command.

subcommands: List[Subcommand]

subparser: Any | None = None: A subparser, auto-populated if subcommand_types is not None.

plugins functions

add_command_subparsers

polytracker.plugins.add_command_subparsers(parser: ArgumentParser): Adds subparsers for all PolyTracker commands