diff --git a/README.md b/README.md index aa8c6aa..2eb9e09 100644 --- a/README.md +++ b/README.md @@ -165,4 +165,103 @@ A `location` plugin which constructs the resulting URI that the uploaded file ca ## Documentation - Plugin Development -Coming soon... +A plugin for SSHare is just a python file (`*.py`). There are currently 6 types of plugins: +- `logger` +- `source` +- `name` +- `upload` +- `location` +- `feedback` +A plugin can specify be any combination of the above types. For examples of plugins see [here](src/sshare/plugins) +and [here](https://forge.monodon.me/Gnarwhal/sshare_plugins) + +### General Attributes + +Every plugin regardless of type specifies or is provided with these attributes. + +#### `plugin_type` + +This mandatory paramater specifies what type(s) this plugin is. +It can be either a: +- `string` - Promotes to `{ string }` +- `set` - A set containing each of the plugin's types. + +#### `activate` + +This optional parameter specifies what flag(s) or argument(s) must be passed for this plugin to be activated. +It can be either a: +- `string` - Promotes to `{ string }` +- `set` - Promotes to `{ plugin_type: { string, ... }, plugin_type2: { string, ... }, ... }` +- `dict` - A dictionary that maps each type the plugin is, to the flags or arguments that activate the plugin for that type +All arguments specified in `activate` must be provided by the user for the plugin to activate. + +#### `config` + +This optional parameter specifies configuration options for the plugin. These values are what a user is allowed to change +through `config.toml`. It is a map containing `{ option: default_value, ... }`. If there is no default value (i.e. it is mandatory +that the user set it explicitly) for the option, it can be set to `NoDefault` provided by +`from sshare.plugin.config import NoDefault`. + +While `config` is initially specified as a `dict`, when the plugin is loaded it will be converted to an object with attributes. +For example, if a config is specified as +```python +config = { + "example0": 42, +} +``` +it would then be accessed by `config.example` not `config["example"]`. + +#### `args` + +This optional parameter specifies arguments for the plugin. These values are also accessed from the `config` object, +however they are provided via program arguments as opposed to being specified in `config.toml`. An option specified +in both `config` and `args` will be loaded from the config file first and overriden by the program argument if +provided. Arguments are of type `Argument` provided by `from sshare.plugin.config import Argument`. +`Argument` takes `name` (optionally) and a list of `kwargs` equivalent to the option document [here](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_argument). As a convenience there is also `Flag` provided by +`from sshare.plugin.config import Flag`, which is for boolean arguments which take no parameters. +`Flag` only takes a `help=...` paramater. + +#### `init` + +If a plugin needs to do any initialisation, it can be done in the `init` method. The `init` method takes no parameters +and returns no values. + +#### `logger` + +Logger is not specified by the plugin developer, but is available inside the plugin if needed. The logger +has three levels: `info`, `warn` and `error`. + +### Type Specific Attributes + +#### `logger` +- `info(str)` +- `warn(str)` +- `error(str)` + +#### `source` -> `get_source()` + +The `get_source` function takes no arguments and returns a source. There are currently two types of sources provided by +`from sshare.plugin.source import (Raw | File)`. +- `Raw` - A raw data source. It has a type, a source name, and a byte array providing the data. +- `File` - A file or directory source. It has only the path to the file. + +#### `name` -> `get_name(current_name, source)` + +`name` plugins are chained one after the other. The first `name` plugin is provided an empty string for `current_name`. +Each subsequent `name` plugin is provided the output of the previous `name` plugin's `get_name` function. The `source` +parameter is the either `Raw` or `File` data source. + +#### `upload` -> `upload(name, source)` + +`upload` plugins are responsible for getting the source to the destination. + +#### `location` -> `get_location(name)` + +The `get_location` function takes in the name of a source and returns a location that the source can now be accessed from +(e.g. a URL). + +#### `feedback` -> `give_feedback(location)` + +The `give_feedback` function takes output from `location` plugins and presents it to the user (e.g. printing to console, +desktop notification. etc...). + diff --git a/src/sshare/plugins/time.py b/src/sshare/plugins/time.py index 53e9777..b186ca6 100644 --- a/src/sshare/plugins/time.py +++ b/src/sshare/plugins/time.py @@ -44,8 +44,8 @@ def _rebase(base, number): def _number_to_char(number): if number < 10: - return chr(number + 48) + return chr(number + 48) # 0-9 elif number < 36: - return chr(number + 87) + return chr(number + 87) # a-z else: - return chr(number + 29) + return chr(number + 29) # A-Z