Cleanup part 1
This commit is contained in:
parent
92f5e1f47a
commit
88e5aed667
GPG key ID:
0989A73D8C421174
5 changed files with 147 additions and 21 deletions
153
README.md
153
README.md
|
|
@ -2,11 +2,6 @@
|
|||
|
||||
Upload files to a server via ssh
|
||||
|
||||
## Documentation
|
||||
|
||||
- **End User**: coming soon...
|
||||
- **Plugin Developer**: coming soon...
|
||||
|
||||
## Installing
|
||||
|
||||
SSHare is not available on [PyPI](https://pypi.org).
|
||||
|
|
@ -23,7 +18,151 @@ 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 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
|
||||
|
||||
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...
|
||||
|
|
|
|||
|
|
@ -1,5 +0,0 @@
|
|||
#!/usr/bin/python
|
||||
|
||||
import sys
|
||||
|
||||
print("=> " + sys.stdin.read())
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
#!/usr/bin/python
|
||||
|
||||
for i in range(0, 5):
|
||||
print("\033[91mHello World!")
|
||||
|
|
@ -19,7 +19,7 @@ requires-python = ">=3.11"
|
|||
|
||||
[project.urls]
|
||||
Homepage = "https://forge.monodon.me/Gnarwhal/sshare"
|
||||
Documentation = "https://forge.monodon.me/Gnarwhal/sshare/README.md#Usage"
|
||||
Documentation = "https://forge.monodon.me/Gnarwhal/sshare/README.md"
|
||||
Repository = "https://forge.monodon.me/Gnarwhal/sshare"
|
||||
Issues = "https://forge.monodon.me/Gnarwhal/sshare/issues"
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
from src.sshare.plugin.config import Argument
|
||||
|
||||
def test_foo():
|
||||
assert True
|
||||
Loading…
Reference in a new issue