> For the complete documentation index, see [llms.txt](https://guide.fariaedu.com/professional-learning-community-mbpy/6VBx07Zj330EYGI5zHno/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.fariaedu.com/professional-learning-community-mbpy/6VBx07Zj330EYGI5zHno/plugins/mbpy_plugin_example.md).

# mbpy\_plugin\_example

Description of plugin architecture

### Usage

When the directory structure is complete, go to the mbpy folder, and import it with the following command. Remember you should be in your virtual environment:

```
pip install --editable /path/to/mbpy_plugin_example
```

Check it was successful by inputting the command `mbpy plugins --help` and seeing the name displayed. It can then be executed by typing `mbpy plugins name_of_plugin`.

### Directory Structure

The bare-bones essentials for getting started building a plugin for mbpy, with explanations.

Place the following files into the same directory:

#### `setup.py`:

```
from setuptools import setup

setup(
    name='example',
    version='0.1',
    py_modules=['example'],
    install_requires=[
        'click',
    ],
    entry_points='''
        [mbpy_plugins]
        example=example.cli:cli
    ''',
)
```

> The `name` property can be anything, rename it to whatever makes sense. The `py_modules` value needs to match the name of the module, which in this example is "example". The `entry_points` parameter is where the magic happens. It simply maps out that we will be injecting which module, into where. In this case, it's indicating to inject as an `mbpy_plugin`, so that it'll be available as a subcommand when the user uses `mbpy_plugins --help` to discover how to use it. The path is specified as `example=example.cli:cli` which means "The example module, which has a file called `cli`, which has a function defined as `cli`, and that is the code that will be injected.

#### `example/cli.py`:

```python
import click

@click.command('example')
def cli():
    """
    Example Plugin!
    """
    pass
```

> This is the subcommand that will be added to `mbpy plugins` command. You can specify parameters using the [click](https://click.palletsprojects.com/en/8.1.x/) api interface. There are many example of how to do this in the codebase.

#### `example/__init__.py`

> This is actually a blank file, but required to exist (as this is how a module is created in Python.)

### Common Idioms

The above code is truly bare-bones; there is very little that can be actually accomplished without additional imports and boilerplate.

To continue building, please use the following example idioms:

#### Execute a DB query:

```python
import click
from mbpy.db.schema import Student  # to query Student table

@click.command('your-name')
@click.option('-g', '--grade', 'grade_variable', type=int)
@click.pass_context
def cli(ctx, grade_variable):
    """ Show students in the passed grade """
    with ctx.obj.Session() as session:
        students = session.query(Student) \
                     .where(Student.class_grade_number == grade_number) \
                     .all()
        print(students)
```

With the code installed the user can execute `mbpy plugins your-name --grade 10`.