View on GitHub

Upstream

Instructions for using Upstream

Download this project as a .zip file Download this project as a tar.gz file

NOTE: Upstream is still in an ALPHA state. If you run into bugs or problems with the software, please create an issue on the github issue tracker.

Introduction

Upstream is a command-line uploader that's used to upload the data required to create a River file. It is gevent coroutine-based to allow for multiple articles to be uploaded at once. It also creates the required PAR2 files and uploads them at the same time to upload as fast as possible. The command line is fairly complicated, however allows for flexible River files, including the ability to define River-scoped metadata and file-scoped metadata (things like name, description). Both River-scoped and file-scoped NFOs can also be defined, and automatically uploaded as well. Multithreaded uploads are planned for the future, but are not top priority. Notable features of Upstream are:

Requirements

Downloading

As Upstream is currently in an ALPHA state, the only way to get it is to download a tarball of HEAD or clone from GitHub.

If you know how to use git, clone from https://github.com/isc-usenet/Upstream.git

Otherwise, download the HEAD tarball from https://github.com/isc-usenet/Upstream/tarball/master

Installing

As Upstream is currently in an ALPHA state, there is no method to install it. Enter the directory that Upstream resides in and run the command: python2.7 upstream.py -h This will give you a list of parameters that you can pass to Upstream.

Configuration

As Upstream is currently in an ALPHA state, there is stored configuration, meaning you have to pass all parameters to Upstream directly through the command line.

Usage

Using Upstream is fairly simple - the only required parameter is the "server" parameter. If your Usenet credentials require a username and password, those can also be entered through the parameters of the same name. SSL is also available, and if a port is not specified, the default Usenet SSL port will be set. The more technical parameters (articlesize, segmentsize, parblocks) are set to safe defaults and unless you know what you are doing, they should not be changed.

Examples

python2.7 upstream.py -s news.usenethost.com -u myusername -p mypassword file_to_upload.flac -o myfile.river

This will set your Usenet credentials and upload your file_to_upload.flac file to Usenet on port 119, referring to it in myfile.river The -s parameter is equivalent to --server, -u equivalent to --username, -p equivalent to --password and -o equivalent to --output

python2.7 upstream.py -s news.usenethost.com -u myusername -p mypassword file_to_upload.flac other_file_to_upload.flac -o myfiles.river

This is the same as above, but puts another file into the River.

python2.7 upstream.py -s news.usenethost.com -u myusername -p mypassword file_to_upload.flac -o myfile.river -r

The -r (or --rlink) parameter creates a River Link, which will be printed to screen, and also output to myfile.river.rlink (or output.river.rlink if -o is not specified)

python2.7 upstream.py -s news.usenethost.com -u myusername -p mypassword file_to_upload.flac -o myfile.river -m name="My Uploaded File" -r

The -m (or --meta) parameter is used to set metadata within the river file, such as a human-readable name or description. Meta keys can contain any character that isn't the equals sign, and meta values can contain any character. It is recommended that keys are lowercase.

python2.7 upstream.py -s news.usenethost.com -u myusername -p mypassword file_to_upload.flac -o myfile.river -m name="My Uploaded File" -n file_to_upload.nfo

The -n parameter (or --nfo) uploads an NFO file to usenet and adds an "nfo" key to the metadata with a reference to the uploaded NFO. If an "nfo" key is set in a -m parameter with -n also set, the -n will override the value.

python2.7 upstream.py -s news.usenethost.com -u myusername -p mypassword file_to_upload.flac -o myfile.river --ssl

The --ssl parameter connects to the server with SSL (and changes the port to 563 if not set) and uploads encrypted.

python2.7 upstream.py -s news.usenethost.com -u myusername -p mypassword file_to_upload.flac -o myfile.river --subject "[MY RIVER] \"{name}\""

The --subject parameter changes the default subject that is used in Usenet articles. The string {name} is replaced with the file name.

python2.7 upstream.py -s news.usenethost.com -u myusername -p mypassword file_to_upload.flac -o myfile.river -f file_to_upload.flac/name="My Uploaded File"

The -f parameter (or --filemeta) is used to set file-scoped metadata. The key in this case cannot contain a slash or equal sign character, and the file must be the base name - that is, only the filename without any directory paths.

python2.7 upstream.py -s news.usenethost.com -u myusername -p mypassword file_to_upload.flac -o myfile.river --filenfo file_to_upload.flac=file_to_upload.nfo

This is equivalent to the -n parameter, however it works on a file scope rather than a River scope. This means you can set individual NFOs to separate files.

Notes

Be aware that the --meta, --filemeta and --filenfo parameters are special in that they accept an infinite number of values until it either hits the end of the command line or hits another parameter. This means you cannot define any files right after one of these parameters without first putting a different parameter in front of it. As an example,

python2.7 upstream.py -s news.usenethost.com -u myusername -p mypassword file_to_upload.flac -o myfile.river --filenfo file_to_upload.flac=file_to_upload.nfo

will work perfectly fine, however

python2.7 upstream.py -s news.usenethost.com -u myusername -p mypassword -o myfile.river --filenfo file_to_upload.flac=file_to_upload.nfo file_to_upload.flac

will not, because Upstream will attempt to interpret the filename as a key-value combination.