From c3799b9c8c96108d238ec855a92400c3e8e1b4ce Mon Sep 17 00:00:00 2001 From: Jack Robison Date: Fri, 9 Jun 2017 12:14:03 -0400 Subject: [PATCH] add cli docs --- CHANGELOG.md | 1 + docs/cli.md | 865 +++++++++++++++++++++++++++++++ lbrynet/lbrynet_daemon/Daemon.py | 2 +- mkdocs.yml | 1 + scripts/gen_api_docs.py | 55 +- 5 files changed, 875 insertions(+), 49 deletions(-) create mode 100644 docs/cli.md diff --git a/CHANGELOG.md b/CHANGELOG.md index d343ebb18..afbefb97a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ at anytime. ### Added * Added claim_address option to publish API command * Added message for InsufficientFundsError exception + * Add CLI docs ### Changed * Do not catch base exception in API command resolve diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 000000000..82a2622a5 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,865 @@ +# LBRY Command Line Documentation + +## blob_announce_all + +```text +Announce all blobs to the DHT + +Usage: + blob_announce_all + +Returns: + (str) Success/fail message +``` + +## blob_delete + +```text +Delete a blob + +Usage: + blob_delete ( | --blob_hash= | --blob_hash=) [--timeout=] + [--encoding=] [--payment_rate_manager=] + +Options: +--timeout= : timeout in number of seconds +--encoding= : by default no attempt at decoding is made, + can be set to one of the + following decoders: + 'json' +--payment_rate_manager= : if not given the default payment rate + manager will be used. + supported alternative rate managers: + 'only-free' + +Returns + (str) Success/Fail message or (dict) decoded data +``` + +## blob_list + +```text +Returns blob hashes. If not given filters, returns all blobs known by the blob manager + +Args: + 'uri' (optional): (str) filter by blobs in stream for winning claim + 'stream_hash' (optional): (str) filter by blobs in given stream hash + 'sd_hash' (optional): (str) filter by blobs in given sd hash + 'needed' (optional): (bool) only return needed blobs + 'finished' (optional): (bool) only return finished blobs + 'page_size' (optional): (int) limit number of results returned + 'page' (optional): (int) filter to page x of [page_size] results +Returns: + (list) List of blob hashes +``` + +## blob_reflect_all + +```text +Reflects all saved blobs + +Usage: + blob_reflect_all + +Returns: + (bool) true if successful +``` + +## block_show + +```text +Get contents of a block + +Usage: + block_show ( | --blockhash=) | ( | --height=) + +Options: + , --blockhash= : hash of the block to look up + , --height= : height of the block to look up + +Returns: + (dict) Requested block +``` + +## channel_list_mine + +```text +Get my channels + +Usage: + channel_list_mine + +Returns: + (list) ClaimDict +``` + +## channel_new + +```text +Generate a publisher key and create a new '@' prefixed certificate claim + +Usage: + channel_new ( | --channel_name=) + ( | --amount=) + +Returns: + (dict) Dictionary containing result of the claim + { + 'tx' : (str) hex encoded transaction + 'txid' : (str) txid of resulting claim + 'nout' : (int) nout of the resulting claim + 'fee' : (float) fee paid for the claim transaction + 'claim_id' : (str) claim ID of the resulting claim + } +``` + +## claim_abandon + +```text +Abandon a name and reclaim credits from the claim + +Usage: + claim_abandon ( | --claim_id=) + +Return: + (dict) Dictionary containing result of the claim + { + txid : (str) txid of resulting transaction + fee : (float) fee paid for the transaction + } +``` + +## claim_list + +```text +Get claims for a name + +Usage: + claim_list ( | --name=) + +Returns + (dict) State of claims assigned for the name + { + 'claims': (list) list of claims for the name + [ + { + 'amount': (float) amount assigned to the claim + 'effective_amount': (float) total amount assigned to the claim, + including supports + 'claim_id': (str) claim ID of the claim + 'height': (int) height of block containing the claim + 'txid': (str) txid of the claim + 'nout': (int) nout of the claim + 'supports': (list) a list of supports attached to the claim + 'value': (str) the value of the claim + }, + ] + 'supports_without_claims': (list) supports without any claims attached to them + 'last_takeover_height': (int) the height of last takeover for the name + } +``` + +## claim_list_mine + +```text +List my name claims + +Usage: + claim_list_mine + +Returns + (list) List of name claims owned by user + [ + { + 'address': (str) address that owns the claim + 'amount': (float) amount assigned to the claim + 'blocks_to_expiration': (int) number of blocks until it expires + 'category': (str) "claim", "update" , or "support" + 'claim_id': (str) claim ID of the claim + 'confirmations': (int) number of blocks of confirmations for the claim + 'expiration_height': (int) the block height which the claim will expire + 'expired': (bool) true if expired, false otherwise + 'height': (int) height of the block containing the claim + 'is_spent': (bool) true if claim is abandoned, false otherwise + 'name': (str) name of the claim + 'txid': (str) txid of the cliam + 'nout': (int) nout of the claim + 'value': (str) value of the claim + }, + ] +``` + +## claim_new_support + +```text +Support a name claim + +Usage: + claim_new_support ( | --name=) ( | --claim_id=) + ( | --amount) + +Return: + (dict) Dictionary containing result of the claim + { + txid : (str) txid of resulting support claim + nout : (int) nout of the resulting support claim + fee : (float) fee paid for the transaction + } +``` + +## claim_show + +```text +Resolve claim info from a LBRY name + +Usage: + claim_show [ | --txid=] [ | --nout=] + [ | --claim_id=] + +Options: + , --txid= : look for claim with this txid + , --nout= : look for claim with this nout + , --claim_id= : look for claim with this claim id + +Returns: + (dict) Dictionary contaning claim info, (bool) false if claim is not + resolvable + + { + 'txid': (str) txid of claim + 'nout': (int) nout of claim + 'amount': (float) amount of claim + 'value': (str) value of claim + 'height' : (int) height of claim takeover + 'claim_id': (str) claim ID of claim + 'supports': (list) list of supports associated with claim + } +``` + +## cli_test_command + +```text +This command is only for testing the CLI argument parsing +Usage: + cli_test_command ( | --pos_arg=) + [...] [--pos_arg2=] + [--pos_arg3=] + +Options: + , --pos_arg2= : pos arg 2 + , --pos_arg3= : pos arg 3 + +Returns: + pos args +``` + +## commands + +```text +Return a list of available commands + +Usage: + commands + +Returns: + (list) list of available commands +``` + +## daemon_stop + +```text +Stop lbrynet-daemon + +Usage: + daemon_stop + +Returns: + (string) Shutdown message +``` + +## file_delete + +```text +Delete a LBRY file + +Usage: + file_delete [-a | -f] [--sd_hash=] [--file_name=] + [--stream_hash=] [--claim_id=] + [--outpoint=] [--rowid=] + [--name=] + +Options: + -a : delete file from downloads and delete stored blobs + -f : delete only from downloads, do not delete blobs + --sd_hash= : delete by file sd hash + --file_name : delete by file name in downloads folder + --stream_hash= : delete by file stream hash + --claim_id= : delete by file claim id + --outpoint= : delete by file claim outpoint + --rowid= : delete by file row id + --name= : delete by associated name claim of file + +Returns: + (bool) true if deletion was successful +``` + +## file_list + +```text +List files limited by optional filters + +Usage: + file_list [--sd_hash=] [--file_name=] [--stream_hash=] + [--claim_id=] [--outpoint=] [--rowid=] + [--name=] + [-f] + +Options: + --sd_hash= : get file with matching sd hash + --file_name= : get file with matching file name in the + downloads folder + --stream_hash= : get file with matching stream hash + --claim_id= : get file with matching claim id + --outpoint= : get file with matching claim outpoint + --rowid= : get file with matching row id + --name= : get file with matching associated name claim + -f : full status, populate the 'message' and 'size' fields + +Returns: + (list) List of files + + [ + { + 'completed': (bool) true if download is completed, + 'file_name': (str) name of file, + 'download_directory': (str) download directory, + 'points_paid': (float) credit paid to download file, + 'stopped': (bool) true if download is stopped, + 'stream_hash': (str) stream hash of file, + 'stream_name': (str) stream name , + 'suggested_file_name': (str) suggested file name, + 'sd_hash': (str) sd hash of file, + 'name': (str) name claim attached to file + 'outpoint': (str) claim outpoint attached to file + 'claim_id': (str) claim ID attached to file, + 'download_path': (str) download path of file, + 'mime_type': (str) mime type of file, + 'key': (str) key attached to file, + 'total_bytes': (int) file size in bytes, None if full_status is false + 'written_bytes': (int) written size in bytes + 'message': (str), None if full_status is false + 'metadata': (dict) Metadata dictionary + }, + ] +``` + +## file_set_status + +```text +Start or stop downloading a file + +Usage: + file_set_status [--sd_hash=] [--file_name=] + [--stream_hash=] [--claim_id=] + [--outpoint=] [--rowid=] + [--name=] + +Options: + --sd_hash= : set status of file with matching sd hash + --file_name= : set status of file with matching file name in the + downloads folder + --stream_hash= : set status of file with matching stream hash + --claim_id= : set status of file with matching claim id + --outpoint= : set status of file with matching claim outpoint + --rowid= : set status of file with matching row id + --name= : set status of file with matching associated name claim + +Returns: + (str) Confirmation message +``` + +## get + +```text +Download stream from a LBRY name. + +Usage: + get [ | --file_name=] [ | --timeout=] + [ | --download_directory=] + +Options: + : specified name for the downloaded file + : download timeout in number of seconds + : path to directory where file will be saved + +Returns: + (dict) Dictionary contaning information about the stream + { + 'completed': (bool) true if download is completed, + 'file_name': (str) name of file, + 'download_directory': (str) download directory, + 'points_paid': (float) credit paid to download file, + 'stopped': (bool) true if download is stopped, + 'stream_hash': (str) stream hash of file, + 'stream_name': (str) stream name, + 'suggested_file_name': (str) suggested file name, + 'sd_hash': (str) sd hash of file, + 'name': (str) name claim attached to file + 'outpoint': (str) claim outpoint attached to file + 'claim_id': (str) claim ID attached to file, + 'download_path': (str) download path of file, + 'mime_type': (str) mime type of file, + 'key': (str) key attached to file, + 'total_bytes': (int) file size in bytes, None if full_status is false + 'written_bytes': (int) written size in bytes + 'message': (str), None if full_status is false + 'metadata': (dict) Metadata dictionary + } +``` + +## get_availability + +```text +Get stream availability for lbry uri + +Usage: + get_availability ( | --uri=) [ | --sd_timeout=] + [ | --peer_timeout=] + +Options: + , --sd_timeout= : sd blob download timeout + , --peer_timeout= : how long to look for peers + +Returns: + (float) Peers per blob / total blobs +``` + +## help + +```text +Return a useful message for an API command + +Usage: + help [ | --command=] + +Options: + , --command= : command to retrieve documentation for +``` + +## peer_list + +```text +Get peers for blob hash + +Usage: + peer_list ( | --blob_hash=) [ | --timeout=] + +Options: + , --timeout= : peer search timeout in seconds + +Returns: + (list) List of contacts +``` + +## publish + +```text +Make a new name claim and publish associated data to lbrynet, +update over existing claim if user already has a claim for name. + +Fields required in the final Metadata are: + 'title' + 'description' + 'author' + 'language' + 'license' + 'nsfw' + +Metadata can be set by either using the metadata argument or by setting individual arguments +fee, title, description, author, language, license, license_url, thumbnail, preview, nsfw, +or sources. Individual arguments will overwrite the fields specified in metadata argument. + +Usage: + publish ( | --name=) ( | --bid=) [--metadata=] + [--file_path=] [--fee=] [--title=] + [--description=<description>] [--author=<author>] [--language=<language>] + [--license=<license>] [--license_url=<license_url>] [--thumbnail=<thumbnail>] + [--preview=<preview>] [--nsfw=<nsfw>] [--sources=<sources>] + [--channel_name=<channel_name>] [--channel_id=<channel_id>] + [--claim_address=<claim_address>] + +Options: + --metadata=<metadata> : ClaimDict to associate with the claim. + --file_path=<file_path> : path to file to be associated with name. If provided, + a lbry stream of this file will be used in 'sources'. + If no path is given but a metadata dict is provided, + the source from the given metadata will be used. + --fee=<fee> : Dictionary representing key fee to download content: + { + 'currency': currency_symbol, + 'amount': float, + 'address': str, optional + } + supported currencies: LBC, USD, BTC + If an address is not provided a new one will be + automatically generated. Default fee is zero. + --title=<title> : title of the publication + --description=<description> : description of the publication + --author=<author> : author of the publication + --language=<language> : language of the publication + --license=<license> : publication license + --license_url=<license_url> : publication license url + --thumbnail=<thumbnail> : thumbnail url + --preview=<preview> : preview url + --nsfw=<nsfw> : title of the publication + --sources=<sources> : {'lbry_sd_hash':sd_hash} specifies sd hash of file + --channel_name=<channel_name> : name of the publisher channel name in the wallet + --channel_id=<channel_id> : claim id of the publisher channel, does not check + for channel claim being in the wallet. This allows + publishing to a channel where only the certificate + private key is in the wallet. + --claim_address=<claim_address> : address where the claim is sent to, if not specified + new address wil automatically be created + +Returns: + (dict) Dictionary containing result of the claim + { + 'tx' : (str) hex encoded transaction + 'txid' : (str) txid of resulting claim + 'nout' : (int) nout of the resulting claim + 'fee' : (float) fee paid for the claim transaction + 'claim_id' : (str) claim ID of the resulting claim + } +``` + +## reflect + +```text +Reflect a stream + +Usage: + reflect (<sd_hash> | --sd_hash=<sd_hash>) + +Returns: + (bool) true if successful +``` + +## report_bug + +```text +Report a bug to slack + +Usage: + report_bug (<message> | --message=<message>) + +Returns: + (bool) true if successful +``` + +## resolve + +```text +Resolve a LBRY URI + +Usage: + resolve <uri> [-f] + +Options: + -f : force refresh and ignore cache + +Returns: + None if nothing can be resolved, otherwise: + If uri resolves to a channel or a claim in a channel: + 'certificate': { + 'address': (str) claim address, + 'amount': (float) claim amount, + 'effective_amount': (float) claim amount including supports, + 'claim_id': (str) claim id, + 'claim_sequence': (int) claim sequence number, + 'decoded_claim': (bool) whether or not the claim value was decoded, + 'height': (int) claim height, + 'depth': (int) claim depth, + 'has_signature': (bool) included if decoded_claim + 'name': (str) claim name, + 'supports: (list) list of supports [{'txid': txid, + 'nout': nout, + 'amount': amount}], + 'txid': (str) claim txid, + 'nout': (str) claim nout, + 'signature_is_valid': (bool), included if has_signature, + 'value': ClaimDict if decoded, otherwise hex string + } + If uri resolves to a channel: + 'claims_in_channel': [ + { + 'address': (str) claim address, + 'amount': (float) claim amount, + 'effective_amount': (float) claim amount including supports, + 'claim_id': (str) claim id, + 'claim_sequence': (int) claim sequence number, + 'decoded_claim': (bool) whether or not the claim value was decoded, + 'height': (int) claim height, + 'depth': (int) claim depth, + 'has_signature': (bool) included if decoded_claim + 'name': (str) claim name, + 'supports: (list) list of supports [{'txid': txid, + 'nout': nout, + 'amount': amount}], + 'txid': (str) claim txid, + 'nout': (str) claim nout, + 'signature_is_valid': (bool), included if has_signature, + 'value': ClaimDict if decoded, otherwise hex string + } + ] + If uri resolves to a claim: + 'claim': { + 'address': (str) claim address, + 'amount': (float) claim amount, + 'effective_amount': (float) claim amount including supports, + 'claim_id': (str) claim id, + 'claim_sequence': (int) claim sequence number, + 'decoded_claim': (bool) whether or not the claim value was decoded, + 'height': (int) claim height, + 'depth': (int) claim depth, + 'has_signature': (bool) included if decoded_claim + 'name': (str) claim name, + 'channel_name': (str) channel name if claim is in a channel + 'supports: (list) list of supports [{'txid': txid, + 'nout': nout, + 'amount': amount}] + 'txid': (str) claim txid, + 'nout': (str) claim nout, + 'signature_is_valid': (bool), included if has_signature, + 'value': ClaimDict if decoded, otherwise hex string + } + } +``` + +## resolve_name + +```text +Resolve stream info from a LBRY name + +Usage: + resolve_name <name> [-f] + +Options: + -f : force refresh and do not check cache + +Returns: + (dict) Metadata dictionary from name claim, None if the name is not + resolvable +``` + +## send_amount_to_address + +```text +Queue a payment of credits to an address + +Usage: + send_amount_to_address (<amount> | --amount=<amount>) (<address> | --address=<address>) + +Returns: + (bool) true if payment successfully scheduled +``` + +## settings_get + +```text +Get daemon settings + +Usage: + settings_get + +Returns: + (dict) Dictionary of daemon settings + See ADJUSTABLE_SETTINGS in lbrynet/conf.py for full list of settings +``` + +## settings_set + +```text +Set daemon settings + +Args: + 'run_on_startup': (bool) currently not supported + 'data_rate': (float) data rate, + 'max_key_fee': (float) maximum key fee, + 'download_directory': (str) path of where files are downloaded, + 'max_upload': (float), currently not supported + 'max_download': (float), currently not supported + 'download_timeout': (int) download timeout in seconds + 'search_timeout': (float) search timeout in seconds + 'cache_time': (int) cache timeout in seconds +Returns: + (dict) Updated dictionary of daemon settings +``` + +## status + +```text +Get daemon status + +Usage: + status [-s] [-d] + +Options: + -s : include session status in results + -d : include dht network and peer status +``` + +## stream_cost_estimate + +```text +Get estimated cost for a lbry stream + +Usage: + stream_cost_estimate <uri> [<size> | --size=<size>] + +Options: + <size>, --size=<size> : stream size in bytes. if provided an sd blob won't be + downloaded. + +Returns: + (float) Estimated cost in lbry credits, returns None if uri is not + resolveable +``` + +## transaction_list + +```text +List transactions belonging to wallet + +Usage: + transaction_list + +Returns: + (list) List of transactions +``` + +## transaction_show + +```text +Get a decoded transaction from a txid + +Usage: + transaction_show (<txid> | --txid=<txid>) + +Returns: + (dict) JSON formatted transaction +``` + +## version + +```text +Get lbry version information + +Usage: + version + +Returns: + (dict) Dictionary of lbry version information + { + 'build': (str) build type (e.g. "dev", "rc", "release"), + 'ip': (str) remote ip, if available, + 'lbrynet_version': (str) lbrynet_version, + 'lbryum_version': (str) lbryum_version, + 'lbryschema_version': (str) lbryschema_version, + 'os_release': (str) os release string + 'os_system': (str) os name + 'platform': (str) platform string + 'processor': (str) processor type, + 'python_version': (str) python version, + } +``` + +## wallet_balance + +```text +Return the balance of the wallet + +Usage: + wallet_balance [<address> | --address=<address>] [-u] + +Options: + <address> : If provided only the balance for this address will be given + -u : Include unconfirmed + +Returns: + (float) amount of lbry credits in wallet +``` + +## wallet_is_address_mine + +```text +Checks if an address is associated with the current wallet. + +Usage: + wallet_is_address_mine (<address> | --address=<address>) + +Returns: + (bool) true, if address is associated with current wallet +``` + +## wallet_list + +```text +List wallet addresses + +Usage: + wallet_list + +Returns: + List of wallet addresses +``` + +## wallet_new_address + +```text +Generate a new wallet address + +Usage: + wallet_new_address + +Returns: + (str) New wallet address in base58 +``` + +## wallet_public_key + +```text +Get public key from wallet address + +Usage: + wallet_public_key (<address> | --address=<address>) + +Returns: + (list) list of public keys associated with address. + Could contain more than one public key if multisig. +``` + +## wallet_unused_address + +```text +Return an address containing no balance, will create +a new address if there is none. + +Usage: + wallet_unused_address + +Returns: + (str) Unused wallet address in base58 +``` + diff --git a/lbrynet/lbrynet_daemon/Daemon.py b/lbrynet/lbrynet_daemon/Daemon.py index 044fea5c8..84ee355ee 100644 --- a/lbrynet/lbrynet_daemon/Daemon.py +++ b/lbrynet/lbrynet_daemon/Daemon.py @@ -2184,7 +2184,7 @@ class Daemon(AuthJSONRPCServer): Usage: blob_delete (<blob_hash> | --blob_hash=<blob_hash) -t + Returns: (str) Success/fail message """ diff --git a/mkdocs.yml b/mkdocs.yml index 7d8cc6f5c..6a700297c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,6 +2,7 @@ site_name: LBRY repo_url: https://github.com/lbryio/lbry pages: - "API": index.md + - "CLI": cli.md theme: material site_dir: docs_build google_analytics: diff --git a/scripts/gen_api_docs.py b/scripts/gen_api_docs.py index 7e999ba10..055bb2bfc 100644 --- a/scripts/gen_api_docs.py +++ b/scripts/gen_api_docs.py @@ -9,7 +9,6 @@ import os.path as op import re import sys -from six import string_types from lbrynet.lbrynet_daemon.Daemon import Daemon @@ -41,41 +40,7 @@ def _replace_docstring_header(paragraph): def _doc(obj): docstr = (inspect.getdoc(obj) or '').strip() - return _replace_docstring_header(docstr) if docstr and '---' in docstr else docstr - - -def _is_public(obj): - name = _name(obj) if not isinstance(obj, string_types) else obj - if name: - return not name.startswith('_') - else: - return True - - -def _is_defined_in_package(obj, package): - if isinstance(obj, property): - obj = obj.fget - mod = inspect.getmodule(obj) - if mod and hasattr(mod, '__name__'): - name = mod.__name__ - return name.split('.')[0] == package - return True - - -def _iter_doc_members(obj, package=None): - for _, member in inspect.getmembers(obj): - if _is_public(member): - if package is None or _is_defined_in_package(member, package): - yield member - - -def _iter_methods(klass, package=None): - for member in _iter_doc_members(klass, package): - if inspect.isfunction(member) or inspect.ismethod(member): - if inspect.isdatadescriptor(member): - continue - if _name(member).startswith('jsonrpc_'): - yield member + return _replace_docstring_header(docstr) def _link(name, anchor=None): @@ -84,24 +49,18 @@ def _link(name, anchor=None): def main(): curdir = op.dirname(op.realpath(__file__)) - path = op.realpath(op.join(curdir, '..', 'docs', 'index.md')) - - klass = Daemon + cli_doc_path = op.realpath(op.join(curdir, '..', 'docs', 'cli.md')) # toc = '' doc = '' # Table of contents - for method in _iter_methods(klass): - method_name = _name(method)[len('jsonrpc_'):] - method_doc = _doc(method) - if "DEPRECATED" in method_doc: - continue + for method_name in sorted(Daemon.callable_methods.keys()): + method = Daemon.callable_methods[method_name] # toc += '* ' + _link(method_name, _anchor(method_name)) + "\n" - doc += '## ' + method_name + "\n\n```text\n" + method_doc + "\n```\n\n" + doc += '## ' + method_name + "\n\n```text\n" + _doc(method) + "\n```\n\n" - text = "# LBRY JSON-RPC API Documentation\n\n" + doc - - with open(path, 'w+') as f: + text = "# LBRY Command Line Documentation\n\n" + doc + with open(cli_doc_path, 'w+') as f: f.write(text)