sshare/README.md

169 lines
5.9 KiB
Markdown
Raw Normal View History

2024-07-31 15:06:45 +00:00
# SSHare
Upload files to a server via ssh
2024-07-31 15:06:45 +00:00
2024-09-08 22:47:30 +00:00
## Installing
2024-08-01 06:01:23 +00:00
2024-09-08 22:47:30 +00:00
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
2024-08-01 06:01:23 +00:00
```
2024-09-08 22:47:30 +00:00
git clone https://forge.monodon.me/Gnarwhal/sshare.git
cd sshare
pip install ./
2024-08-01 06:01:23 +00:00
```
2024-09-08 22:47:30 +00:00
By default, the only dependency SSHare has is the system's `ssh` (and `scp`) commands.
Beyond that it only utilises the python standard library.
2024-08-01 06:01:23 +00:00
2024-09-08 22:47:30 +00:00
### Additional Functionality
2024-08-01 06:01:23 +00:00
2024-09-08 22:47:30 +00:00
The base install is fairly bare bones in terms of functionality.
2024-09-25 04:18:00 +00:00
Included in the [`examples/`](https://forge.monodon.me/Gnarwhal/sshare_plugins) submodule, there is a sampling of
2024-09-08 22:47:30 +00:00
plugins which provide some additional conveniences
2024-08-01 06:01:23 +00:00
2024-09-25 04:18:00 +00:00
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
Coming soon...