12. Packages Structure

To make Plugins easier to distribute, Keypirinha has been introduced the concept of Packages.

In Keypirinha, a package is a container that groups one or several plugins designed to work together, as well as optional configuration files and dependencies.

A package can take the form of a directory containing loose files, or a Zip archive with the .keypirinha-package extension (for redistribution).

12.1. Packages Repositories

There are four repositories of packages. In order of descending priority:

Except for the Internal Package type, the only difference between those Repositories is the way they are stored and their location.

Important

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.

12.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.

Note

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 .ini file is modified, the application will call the keypirinha.Plugin.on_events() method of every plugin that belong to the parent package instead of fully reloading it.

12.1.2. Installed Packages (Downloaded)

Packages are meant to be easily redistributable and installable. A dedicated directory called InstalledPackages under user’s directory is available for this purpose.

Package files are Zip archives with the .keypirinha-package extension.

12.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 .keypirinha-package extension and are stored in the default/Packages directory directly located under Keypirinha’s installation directory.

12.1.4. Internal Package

Internal is actually both a type of package and the name of the package itself.

The Internal package is implemented in the application itself and its behavior is unalterable. Any other type of package is said to be external.

See Internal Package for more information about how to use this package.

12.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:

    • all

    • app

    • application

    • builtin

    • builtins

    • cache

    • data

    • default

    • env

    • extern

    • external

    • hook

    • icon

    • image

    • intern

    • internal

    • kpsdk

    • local

    • locale

    • main

    • name

    • nil

    • none

    • null

    • official

    • package

    • plugin

    • python

    • res

    • resource

    • sdk

    • temp

    • theme

    • tmp

    • type

    • script

    • user

    • var

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.