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

Coming soon...