sshare/README.md

SSHare

Upload files to a server via ssh

Installing

SSHare is not available on PyPI. 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/ 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

[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

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

flags

[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 specs. 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 and here

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

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