267 lines
10 KiB
Markdown
267 lines
10 KiB
Markdown
# SSHare
|
|
|
|
Upload files to a server via ssh
|
|
|
|
## Installing
|
|
|
|
SSHare is not available on [PyPI](https://pypi.org).
|
|
To install it you will need to clone the repo and use pip to install it
|
|
```
|
|
git clone https://forge.monodon.me/Gnarwhal/sshare.git
|
|
cd sshare
|
|
pip install ./
|
|
```
|
|
|
|
By default, the only dependency SSHare has is the system's `ssh` (and `scp`) commands.
|
|
Beyond that it only utilises the python standard library.
|
|
|
|
### Additional Functionality
|
|
|
|
The base install is fairly bare bones in terms of functionality.
|
|
Included in the [`examples/`](https://forge.monodon.me/Gnarwhal/sshare_plugins) submodule, there is a sampling of
|
|
plugins which provide some additional conveniences
|
|
|
|
Refer to the above documentation for information on installing plugins
|
|
|
|
## Documentation - End User
|
|
|
|
Getting started with SSHare is about getting familiar with configuring SSHare.
|
|
SSHare configuration is all done in the `${XDG_CONFIG_DIR}/sshare` if set, or in `~/.config/sshare` otherwise.
|
|
In this directory are two important items: the `config.toml` file and the `plugins/` directory.
|
|
|
|
### `plugins/`
|
|
|
|
The `plugins/` directory is home to all external plugins. Installing a plugin is as simple as saving the
|
|
the plugin's `.py` file to the `plugins/`.
|
|
|
|
### `config.toml`
|
|
|
|
The configuration file can be broken down into three major components: `spec`, `config`, and `flags`.
|
|
|
|
#### `spec`
|
|
|
|
```toml
|
|
|
|
[spec.default]
|
|
name = [ "time", "extension" ]
|
|
|
|
[spec.example]
|
|
flag = { short = "e", long = "example" }
|
|
name = [ "preserve", "extension" ]
|
|
|
|
[spec.noshort]
|
|
flag = { long = "only" }
|
|
name = [ "time" ]
|
|
help = "No short flag, only long flag >:("
|
|
```
|
|
|
|
The `spec` section is a collection of different runtime specifications. The name of a specification is
|
|
unimportant with the exception of `default`, which is run when no other spec is activated. In each specification
|
|
that isn't `default`, there is a `flag` attribute that sets which command line arguments activate the
|
|
specification. The `flag` attribute must have one or both of `short` or `long`, where `short` will be set the flag
|
|
`-{short}` and `long` will set the flag `--{long}`. The `name` attribute of a specification is an array of name type
|
|
plugins which controls the order in which said plugins are executed. Specifications can also provide a brief description
|
|
in the `help` attribute, which will be displayed when `sshare --help` is run. In the example above,
|
|
running `sshare --help` would give
|
|
```
|
|
options:
|
|
-e, --example Use example spec
|
|
--only No short flag, only long flag >:(
|
|
```
|
|
#### `config`
|
|
|
|
```toml
|
|
[config.ssh]
|
|
host = "example.com"
|
|
path = "/directory/to/store/files/in"
|
|
port = 22
|
|
```
|
|
|
|
The `config` section is used to set configuration options for plugins. Refer to documentation for a plugin to see
|
|
what options can be set here. Documentation for default plugins is included [below](#Default-Plugins).
|
|
|
|
#### `flags`
|
|
|
|
```toml
|
|
[flags.file]
|
|
file = { short = "f" }
|
|
|
|
[flags.stdin]
|
|
stdin = { short = "" }
|
|
|
|
[flags.example]
|
|
option = { short = "o", long = "ooooption" }
|
|
```
|
|
|
|
The `flags` section is used to bind plugin arguments to a command line argument. They are specified in the same way
|
|
as the `flag` option for `spec`s. If `long` is left unspecified, the long flag will be set to the default provided by
|
|
the plugin. In the example above, running `sshare --help` would give:
|
|
```
|
|
options:
|
|
-f file, --file file Upload a file
|
|
-, --stdin Upload from stdin
|
|
-o xmpl, --ooooption xmpl
|
|
This is not a real plugin that exists
|
|
```
|
|
|
|
### Default Plugins
|
|
|
|
#### `command_line`
|
|
|
|
A `logger` plugin which prints to the command line. No configuration needed.
|
|
|
|
#### `extension`
|
|
|
|
A `name` plugin which appends the source type to the end of the file name (i.e. `txt`, `png`, etc...). No configuration needed.
|
|
|
|
#### `file`
|
|
|
|
A `source` plugin which provides a file to be uploaded. File is specified with the `--file {file_path}` argument. No configuration needed.
|
|
|
|
#### `preserve`
|
|
|
|
A `name` plugin which preserves the name of the source in the uploaded file. No configuration needed.
|
|
|
|
#### `print_location`
|
|
|
|
A `feedback` plugin which prints the location that sources can be accessed from. No configuration needed.
|
|
|
|
#### `ssh`
|
|
|
|
An `upload` plugin which uploads the sources to the server using `ssh`.
|
|
|
|
##### Configuration
|
|
| Attribute | Type | Default | Description |
|
|
|-----------|--------|---------|------------------------------------------------------|
|
|
| host | string | None | The hostname to ssh into |
|
|
| path | string | None | The path of the directory to upload the sources into |
|
|
| port | int | 22 | The port to ssh into |
|
|
| user | string | $USER | The user to ssh as |
|
|
|
|
#### `stdin`
|
|
|
|
A `source` plugin which reads from stdin. No configuration needed.
|
|
|
|
#### `time`
|
|
|
|
A `name` plugin which adds the current unix time to the name of the of the uploaded file.
|
|
|
|
##### Configuration
|
|
| Attribute | Type | Default | Description |
|
|
|-----------|--------|---------|------------------------------------------------------|
|
|
| format | int | 62 | The base between 2 and 62 to represent the number in |
|
|
|
|
##### `uri`
|
|
|
|
A `location` plugin which constructs the resulting URI that the uploaded file can be accessed from.
|
|
|
|
##### Configuration
|
|
| Attribute | Type | Default | Description |
|
|
|-----------|--------|---------|------------------------------------------------------|
|
|
| protocol | string | https | The protocol of the URI |
|
|
| host | string | None | The hostname the file can be accessed from |
|
|
| port | int | 22 | The port the file can be accessed at |
|
|
| path | string | None | The path the file can be accessed at |
|
|
|
|
## Documentation - Plugin Development
|
|
|
|
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...).
|
|
|