mirror of
https://github.com/craigerl/aprsd.git
synced 2026-01-13 09:07:35 -05:00
113 lines
3.6 KiB
ReStructuredText
113 lines
3.6 KiB
ReStructuredText
APRSD Command Plugin Development
|
|
================================
|
|
|
|
Creating a Plugin Project
|
|
-------------------------
|
|
|
|
The recommended way to create a new APRSD plugin project is to use the `cookiecutter-aprsd-plugin`_ template. This template provides a complete project structure with all the necessary files, testing infrastructure, and documentation setup.
|
|
|
|
Installation
|
|
~~~~~~~~~~~~
|
|
|
|
First, install cookiecutter if you haven't already::
|
|
|
|
pip install cookiecutter
|
|
|
|
Creating a New Plugin Project
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Run cookiecutter with the APRSD plugin template::
|
|
|
|
cookiecutter gh:hemna/cookiecutter-aprsd-plugin
|
|
|
|
Cookiecutter will prompt you for several pieces of information:
|
|
|
|
* **plugin_name**: The name of your plugin (e.g., ``aprsd-my-plugin``)
|
|
* **plugin_module_name**: The Python module name (e.g., ``aprsd_my_plugin``)
|
|
* **author_name**: Your name or organization name
|
|
* **author_email**: Your email address
|
|
* **description**: A brief description of your plugin
|
|
* **version**: Initial version (default: ``0.1.0``)
|
|
|
|
Project Structure
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
The cookiecutter template creates a complete project structure including:
|
|
|
|
* **Test automation** with Tox
|
|
* **Linting** with pre-commit and Flake8
|
|
* **Continuous integration** with GitHub Actions
|
|
* **Documentation** with Sphinx and Read the Docs
|
|
* **Automated uploads** to PyPI and TestPyPI
|
|
* **Automated dependency updates** with Dependabot
|
|
* **Code formatting** with Gray
|
|
* **Testing** with pytest
|
|
* **Code coverage** with Coverage.py
|
|
* **Coverage reporting** with Codecov
|
|
|
|
The generated project follows Python packaging best practices and includes:
|
|
|
|
* Proper ``setup.py`` and ``pyproject.toml`` configuration
|
|
* Entry point registration for APRSD plugin discovery
|
|
* Test suite structure
|
|
* Documentation templates
|
|
* CI/CD pipeline configuration
|
|
|
|
For more information about the cookiecutter template, visit the `cookiecutter-aprsd-plugin repository`_.
|
|
|
|
.. _cookiecutter-aprsd-plugin: https://github.com/hemna/cookiecutter-aprsd-plugin
|
|
.. _cookiecutter-aprsd-plugin repository: https://github.com/hemna/cookiecutter-aprsd-plugin
|
|
|
|
APRSDPluginBase
|
|
------------------------
|
|
|
|
Plugins are written as python objects that extend the APRSDPluginBase class.
|
|
This is an abstract class that has several properties and a method that must be implemented
|
|
by your subclass.
|
|
|
|
Properties
|
|
----------
|
|
|
|
* name - the Command name
|
|
* regex - The regular expression that if matched against the incoming APRS message,
|
|
will cause your plugin to be called.
|
|
|
|
Methods
|
|
-------
|
|
|
|
* command - This method is called when the regex matches the incoming message from APRS.
|
|
If you want to send a message back to the sending, just return a string
|
|
in your method implementation. If you get called and don't want to reply, then
|
|
you should return a messaging.NULL_MESSAGE to signal to the plugin processor
|
|
that you got called and processed the message correctly. Otherwise a usage
|
|
string may get returned to the sender.
|
|
|
|
|
|
Example Plugin
|
|
--------------
|
|
|
|
There is an example plugin in the aprsd source code here:
|
|
aprsd/examples/plugins/example_plugin.py
|
|
|
|
.. code-block:: python
|
|
|
|
import logging
|
|
|
|
from aprsd import plugin
|
|
|
|
LOG = logging.getLogger("APRSD")
|
|
|
|
|
|
class HelloPlugin(plugin.APRSDRegexCommandPluginBase):
|
|
"""Hello World."""
|
|
|
|
version = "1.0"
|
|
# matches any string starting with h or H
|
|
command_regex = "^[hH]"
|
|
command_name = "hello"
|
|
|
|
def process(self, packet):
|
|
LOG.info("HelloPlugin")
|
|
reply = "Hello '{}'".format(packet.from_call)
|
|
return reply
|