<commit_before>========
Usage
========

To use plugz in a project::

	import plugz<commit_msg>provide introduction on how to use the lib<commit_after>========
Usage
========

plugz will let you define custom types of plugins. You will then derive from your new type to create plugin classes and provide plugz with the location of these new plugins. plugz can then provide you with a loading mechanism for these plugin classes.

The main idea is to derive your custom plugin type from plugz.PluginTypeBase and
declare all the methods that plugins will need to implement as abstract. Look at how a type that plugz ships with is implemented:

.. literalinclude:: /../plugz/plugintypes/standard_plugin_type.py

Just include the implementation of your custom type in your application and pass it on to plugz when necessary. How to do that is described later when we show the load_plugins() function.

The according plugins can look like the following. Note the usage of plugz.register_plugin.

.. literalinclude:: /../tests/data/plugins/standard/valid/plugin_one.py

Given that you defined a plugin type like described above, as well as plugins that derive correctly from it, the following simple instructions will return a list of all registered, valid plugin classes:

>>> import plugz
>>> import my_host_app.MyNewPluginType
>>> plugins = plugz.load_plugins(['/path/to/my/plugins/'], my_host_app.MyNewPluginType)

.. note:: plugz will return a list of class objects and not a list of instances of these objects! You will need to initialize your plugins yourself if you need an actual instance.

{'fraction_non_alphanumeric': 0.071024512884978, 'fraction_numerical': 0.0, 'mean_word_length': 4.625441696113074, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 12, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5646130', 'n_tokens_mistral': 389, 'n_tokens_neox': 383, 'n_words': 219}