Cleanup part 1

This commit is contained in:
Gnarwhal 2024-09-25 04:18:00 +00:00
parent 92f5e1f47a
commit 749cee495a
Signed by: Gnarwhal
GPG key ID: 0989A73D8C421174
4 changed files with 146 additions and 20 deletions

153
README.md
View file

@ -2,11 +2,6 @@
Upload files to a server via ssh Upload files to a server via ssh
## Documentation
- **End User**: coming soon...
- **Plugin Developer**: coming soon...
## Installing ## Installing
SSHare is not available on [PyPI](https://pypi.org). SSHare is not available on [PyPI](https://pypi.org).
@ -23,7 +18,151 @@ Beyond that it only utilises the python standard library.
### Additional Functionality ### Additional Functionality
The base install is fairly bare bones in terms of 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 are included some Included in the [`examples/`](https://forge.monodon.me/Gnarwhal/sshare_plugins) submodule, there is a sampling of
plugins which provide some additional conveniences plugins which provide some additional conveniences
Refer to \[coming soon...\] for information on installing plugins 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...

View file

@ -1,5 +0,0 @@
#!/usr/bin/python
import sys
print("=> " + sys.stdin.read())

View file

@ -1,4 +0,0 @@
#!/usr/bin/python
for i in range(0, 5):
print("\033[91mHello World!")

View file

@ -1,4 +0,0 @@
from src.sshare.plugin.config import Argument
def test_foo():
assert True