11. Packages Structure¶
In Keypirinha, a package is a container (e.g.: a directory; or a Zip archive with
.keypirinha-package extension) that groups one or several plugins
designed to work together. It also contains the configuration files and
dependencies, if any.
11.1. Packages Repositories¶
There are four repositories of packages. In order of descending priority:
- Live Packages: individual directories with loose files
- Installed Packages (Downloaded): Zip archives with the
.keypirinha-packageextension, downloaded and/or installed manually by the user.
- Official Packages (Shipped): Zip archives with the
.keypirinha-packageextension. Packages officially supported and shipped with the application.
- Internal Package Hard-coded in the application.
Except for the Internal Package type, the only difference between those Repositories is the way they are stored and their location.
A Package content can span over multiple Repositories. This is convenient if you wish to modify an Installed or Official package like its source code for example, without having to alter the original files.
For that reason, there is an order of precedence when loading a Package and if two files with the same name belong to the same Package, the file located in the Repository with the highest priority will override the others.
11.1.1. Live Packages¶
Live packages, or Loose packages, are individual directories containing loose
files. They are located under the
Packages directory in user’s folder.
This is the place to start if you wish to create your own package or to modify an existing one.
Package naming is pretty strict and Keypirinha will silently ignore a Package if its name does not comply to the rules described in the Package Naming section below.
This Repository is named Live because it is the only one that allows file
change at runtime. May it be to configuration files, to its source code or any
other resource, the Package will be reloaded soon after a file has been
modified, renamed or delete. However, note that if only an
is modified, the application will broadcast the
CONFIG_CHANGED message (see
keypirinha.Plugin.on_config_changed()) to the plugins of the concerned
package instead of fully reloading it.
11.1.2. Installed Packages (Downloaded)¶
Packages are meant to be easily redistributable and installable. A dedicated
InstalledPackages under user’s directory is available
for this purpose.
Package files are Zip archives with the
11.1.3. Official Packages (Shipped)¶
The Official packages are shipped with every Keypirinha‘s distribution. They are
individually packed in a Zip archive with the
extension and are stored in the
default/Packages directory directly
located under Keypirinha‘s installation directory.
11.1.4. Internal Package¶
Internal is actually both a type of package and the name of the package
Internal package is implemented in the application itself and its
behavior is unalterable. Any other type of package is said to be
See Internal Package for more information about how to use this package.
11.2. Package Naming¶
Rules for package naming:
Name can contain alphanumeric characters (case insensitive) and the following characters:
Name must be at least 3 characters, up to 50
Name must begin and end by an alphanumeric character
Consecutives non-alphanumeric characters are not allowed.
Name must not contain “Keypirinha“
The following names are reserved:
If the name of a Package does not comply to those rules, the Package will be silently ignored by the application and never be loaded until renamed accordingly. Renaming can be done at runtime in this case.