Creating a new filter package¶
Creating a filter package is as easy as creating a directory and putting an
empty __init__.py
file in there. That’s it. That’s your minimal Python
package.
For instance, let us create a filter package called mypackage. Create a
folder called mypackage. Then create an empty file called __init__.py
in
that folder. Instead of mypackage, you may use the name that you like. Keep
in mind, though, that filter package names must be valid Python identifiers, so
you need to avoid hyphens, spaces, and accents; you should only use letters,
underscores and digits, and the name can’t start with a digit.
Then you can put other python files in the package (say myfirstfilter.py
and
mysecondfilter.py
), which define filters. The Python file name without the
.py extension is the name of the filter that you can use in the bibolamazi
file. For instance, we sould have the following file structure:
mypackage/
- __init__.py (empty file)
- myfirstfilter.py (definition of filter myfirstfilter)
- mysecondfilter.py (definition of filter mysecondfilter)
You can then import this filter package in your bibolamazi file using, for instance, the directive:
package: /path/to/mypackage
You can then use myfirstfilter and mysecondfilter as normal filters in your
bibolamazi file. In the following sections, we’ll detail how to write custom
filters so that they can do useful stuff, i.e., we’ll see how we should go about
to code the contents of myfirstfilter.py
and mysecondfilter.py
.
Distributing the filter package as a github repository¶
You can share your filters by creating a github repository to share your filters. The repository must be structured in one of two ways:
- The repository itself contains a folder which is the python package, which itself contains the
__init__.py
file. The python package must have the same name as the repository, with hyphens converted to underscores.- The repository may be the python package itself, i.e., there is a
__init__.py
file at the root of the repository.
Create the repository in this way, and then others can use your filters automatically by including the directive:
package: github:username/repo
You can even keep the repository private, and allow access to your friends; if your friends configure github authentication within bibolamazi as explained here, then they can directly access your filters with the same directive.