diff --git a/CHANGELOG.md b/CHANGELOG.md index e711777da..9e360faa6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,22 @@ at anytime. ### Fixed * + * improper parsing of arguments to CLI settings_set (https://github.com/lbryio/lbry/issues/930) + * unnecessarily verbose exchange rate error (https://github.com/lbryio/lbry/issues/984) + * value error due to a race condition when saving to the claim cache (https://github.com/lbryio/lbry/issues/1013) + * being unable to re-download updated content (https://github.com/lbryio/lbry/issues/951) + * sending error messages for failed api requests + * file manager startup being slow when handling thousands of files + * handling decryption error for blobs encrypted with an invalid key + * handling stream with no data blob (https://github.com/lbryio/lbry/issues/905) + * fetching the external ip + * `blob_list` returning an error with --uri parameter and incorrectly returning `[]` for streams where blobs are known (https://github.com/lbryio/lbry/issues/895) + * `get` failing with a non-useful error message when given a uri for a channel claim + * exception checking in several wallet unit tests + * daemon not erring properly for non-numeric values being passed to the `bid` parameter for the `publish` method + * `publish` command to allow updating claims with a `bid` amount higher than the wallet balance, so long as the amount is less than the wallet balance plus the bid amount of the claim being updated (https://github.com/lbryio/lbry/issues/748) + * incorrect `blob_num` for the stream terminator blob, which would result in creating invalid streams. Such invalid streams are detected on startup and are automatically removed (https://github.com/lbryio/lbry/issues/1124) + * fixed the inconsistencies in docstrings * ### Deprecated @@ -23,6 +39,24 @@ at anytime. ### Changed * * +### Added + * link to instructions on how to change the default peer port + * `lbrynet-console`, a tool to run or connect to lbrynet-daemon and launch an interactive python console with the api functions built in. + * `--conf` CLI flag to specify an alternate config file + * `peer_port`, `disable_max_key_fee`, `auto_renew_claim_height_delta`, `blockchain_name`, and `lbryum_servers` to configurable settings + * `wallet_unlock` command (available during startup to unlock an encrypted wallet) + * support for wallet encryption via new commands `wallet_decrypt` and `wallet_encrypt` + * `channel_import`, `channel_export`, and `claim_renew` commands + * `blob_availability` and `stream_availability` commands for debugging download issues + * a new startup stage to indicate if the daemon is waiting for the `wallet_unlock` command. + * `abandon_info` dictionary (containing `claim_name`, `claim_id`, `address`, `amount`, `balance_delta` and `nout`) for claims, supports, and updates returned by `transaction_list` + * `permanent_url` string to `channel_list_mine`, `claim_list`, `claim_show`, `resolve` and `resolve_name` (see lbryio/lbryum#203) + * `is_mine` boolean to `channel_list` results + * `txid`, `nout`, `channel_claim_id`, `channel_claim_name`, `status`, `blobs_completed`, and `blobs_in_stream` fields to file objects returned by `file_list` and `get` + * `txid`, `nout`, `channel_claim_id`, and `channel_claim_name` filters for `file` commands (`file_list`, `file_set_status`, `file_reflect`, and `file_delete`) + * unit tests for `SQLiteStorage` and updated old tests for relevant changes (https://github.com/lbryio/lbry/issues/1088) + * scripts to autogenerate documentation + * ### Added * @@ -105,6 +139,17 @@ at anytime. * old storage classes used by the file manager, wallet, and blob manager * old `.db` database files from the data directory + * `seccure` and `gmpy` dependencies + * support for positional arguments in cli `settings_set`. Now only accepts settings changes in the form `--setting_key=value` + * `auto_re_reflect` setting from the conf file, use the `reflect_uploads` setting instead + * `name` argument for `claim_show` command + * `message` response field in file objects returned by `file_list` and `get` + * `include_tip_info` argument from `transaction_list`, which will now always include tip information. + * old and unused UI related code + * unnecessary `TempBlobManager` class + * old storage classes used by the file manager, wallet, and blob manager + * old `.db` database files from the data directory + * short(single dashed) arguments ## [0.18.0] - 2017-11-08 ### Fixed diff --git a/docs/cli.md b/docs/cli.md index 8f0c0ff0f..b4a4c579e 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -6,22 +6,47 @@ Announce blobs to the DHT Usage: - blob_announce [-a] [ | --blob_hash=] + blob_announce [--announce_all] [ | --blob_hash=] [ | --stream_hash=] [ | --sd_hash=] + Options: - -a : announce all the blobs possessed by user - , --blob_hash= : announce a blob, specified by blob_hash - , --stream_hash= : announce all blobs associated with - stream_hash - , --sd_hash= : announce all blobs associated with - sd_hash and the sd_hash itself + --announce_all= : (bool) announce all the blobs possessed by user + --blob_hash= : (str) announce a blob, specified by blob_hash + --stream_hash= : (str) announce all blobs associated with + stream_hash + --sd_hash= : (str) announce all blobs associated with + sd_hash and the sd_hash itself Returns: (bool) true if successful ``` +## blob_availability + +```text +Get blob availability + +Usage: + blob_availability () [ | --search_timeout=] + [ | --blob_timeout=] + + +Options: + --blob_hash= : (str) check availability for this blob hash + --search_timeout= : (int) how long to search for peers for the blob + in the dht + --blob_timeout= : (int) how long to try downloading from a peer + +Returns: + (dict) { + "is_available": + "reachable_peers": [":"], + "unreachable_peers": [":"] + } +``` + ## blob_delete ```text @@ -30,6 +55,10 @@ Delete a blob Usage: blob_delete ( | --blob_hash= : (str) blob hash of the blob to delete + Returns: (str) Success/fail message ``` @@ -43,18 +72,20 @@ Usage: blob_get ( | --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 +Options: + --blob_hash= : (str) blob hash of the blob to get + --timeout= : (int) timeout in number of seconds + --encoding= : (str) by default no attempt at decoding + is made, can be set to one of the + following decoders: + 'json' + --payment_rate_manager= : (str) 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 ``` @@ -64,18 +95,21 @@ Returns Returns blob hashes. If not given filters, returns all blobs known by the blob manager Usage: - blob_list [-n] [-f] [ | --uri=] [ | --stream_hash=] - [ | --sd_hash=] [ | --page_size=] + blob_list [--needed] [--finished] [ | --uri=] + [ | --stream_hash=] + [ | --sd_hash=] + [ | --page_size=] [ | --page=] + Options: - -n : only return needed blobs - -f : only return finished blobs - , --uri= : filter blobs by stream in a uri - , --stream_hash= : filter blobs by stream hash - , --sd_hash= : filter blobs by sd hash - , --page_size= : results page size - , --page= : page of results to return + --needed : (bool) only return needed blobs + --finished : (bool) only return finished blobs + --uri= : (str) filter blobs by stream in a uri + --stream_hash= : (str) filter blobs by stream hash + --sd_hash= : (str) filter blobs by sd hash + --page_size= : (int) results page size + --page= : (int) page of results to return Returns: (list) List of blob hashes @@ -89,6 +123,10 @@ Reflects all saved blobs Usage: blob_reflect_all + +Options: + None + Returns: (bool) true if successful ``` @@ -101,9 +139,10 @@ 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 + --blockhash= : (str) hash of the block to look up + --height= : (int) height of the block to look up Returns: (dict) Requested block @@ -117,6 +156,10 @@ Export serialized channel signing information for a given certificate claim id Usage: channel_export ( | --claim_id=) + +Options: + --claim_id= : (str) Claim ID to export information about + Returns: (str) Serialized certificate information ``` @@ -130,6 +173,10 @@ Usage: channel_import ( | --serialized_certificate_info=) + +Options: + --serialized_certificate_info= : (str) certificate info + Returns: (dict) Result dictionary ``` @@ -142,6 +189,10 @@ Get certificate claim infos for channels that can be published to Usage: channel_list + +Options: + None + Returns: (list) ClaimDict, includes 'is_mine' field to indicate if the certificate claim is in the wallet. @@ -156,6 +207,11 @@ Usage: channel_new ( | --channel_name=) ( | --amount=) + +Options: + --channel_name= : (str) name of the channel prefixed with '@' + --amount= : (float) bid amount on the channel + Returns: (dict) Dictionary containing result of the claim { @@ -176,7 +232,13 @@ Usage: claim_abandon [ | --claim_id=] [ | --txid=] [ | --nout=] -Return: + +Options: + --claim_id= : (str) claim_id of the claim to abandon + --txid= : (str) txid of the claim to abandon + --nout= : (int) nout of the claim to abandon + +Returns: (dict) Dictionary containing result of the claim { txid : (str) txid of resulting transaction @@ -192,7 +254,11 @@ List current claims and information about them for a given name Usage: claim_list ( | --name=) -Returns + +Options: + --name= : (str) name of the claim to list info about + +Returns: (dict) State of claims assigned for the name { 'claims': (list) list of claims for the name @@ -205,6 +271,7 @@ Returns 'height': (int) height of block containing the claim 'txid': (str) txid of the claim 'nout': (int) nout of the claim + 'permanent_url': (str) permanent url of the claim, 'supports': (list) a list of supports attached to the claim 'value': (str) the value of the claim }, @@ -223,10 +290,13 @@ Usage: claim_list_by_channel ( | --uri=) [...] [--page=] [--page_size=] + Options: - --page= : which page of results to return where page 1 is the first - page, defaults to no pages - --page_size= : number of results in a page, default of 10 + --uri= : (str) uri of the channel + --uris= : (list) uris of the channel + --page= : (int) which page of results to return where page 1 is the first + page, defaults to no pages + --page_size= : (int) number of results in a page, default of 10 Returns: { @@ -274,7 +344,11 @@ List my name claims Usage: claim_list_mine -Returns + +Options: + None + +Returns: (list) List of name claims owned by user [ { @@ -289,6 +363,7 @@ Returns '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 + 'permanent_url': (str) permanent url of the claim, 'txid': (str) txid of the cliam 'nout': (int) nout of the claim 'value': (str) value of the claim @@ -305,7 +380,13 @@ Usage: claim_new_support ( | --name=) ( | --claim_id=) ( | --amount=) -Return: + +Options: + --name= : (str) name of the claim to support + --claim_id= : (str) claim_id of the claim to support + --amount= : (float) amount of support + +Returns: (dict) Dictionary containing result of the claim { txid : (str) txid of resulting support claim @@ -322,7 +403,12 @@ Renew claim(s) or support(s) Usage: claim_renew ( | --outpoint=) | ( | --height=) -Return: + +Options: + --outpoint= : (str) outpoint of the claim to renew + --height= : (str) update claims expiring before or at this block height + +Returns: (dict) Dictionary where key is the the original claim's outpoint and value is the result of the renewal { @@ -347,9 +433,22 @@ Usage: (
| --address=
) [ | --amount=] + Options: - : Amount of credits to claim name for, defaults to the current amount - on the claim + --claim_id= : (str) claim_id to send + --address=
: (str) address to send the claim to + --amount : (int) Amount of credits to claim name for, defaults to the current amount + on the claim + +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_show @@ -361,12 +460,13 @@ Usage: claim_show [ | --txid=] [ | --nout=] [ | --claim_id=] + Options: - , --txid= : look for claim with this txid, nout must - also be specified - , --nout= : look for claim with this nout, txid must - also be specified - , --claim_id= : look for claim with this claim id + --txid= : (str) look for claim with this txid, nout must + also be specified + --nout= : (int) look for claim with this nout, txid must + also be specified + --claim_id= : (str) look for claim with this claim id Returns: (dict) Dictionary containing claim info as below, @@ -393,15 +493,19 @@ Returns: ```text This command is only for testing the CLI argument parsing Usage: - cli_test_command [-a] [-b] ( | --pos_arg=) + cli_test_command [--a_arg] [--b_arg] ( | --pos_arg=) [...] [--pos_arg2=] [--pos_arg3=] + Options: - -a, --a_arg : a arg - -b, --b_arg : b arg - , --pos_arg2= : pos arg 2 - , --pos_arg3= : pos arg 3 + --a_arg : a arg + --b_arg : b arg + --pos_arg= : pos arg + --pos_args= : pos args + --pos_arg2= : pos arg 2 + --pos_arg3= : pos arg 3 + Returns: pos args ``` @@ -414,6 +518,10 @@ Return a list of available commands Usage: commands + +Options: + None + Returns: (list) list of available commands ``` @@ -426,6 +534,10 @@ Stop lbrynet-daemon Usage: daemon_stop + +Options: + None + Returns: (string) Shutdown message ``` @@ -436,19 +548,28 @@ Returns: Delete a LBRY file Usage: - file_delete [-f] [--delete_all] [--sd_hash=] [--file_name=] - [--stream_hash=] [--rowid=] + file_delete [--delete_from_download_dir] [--delete_all] [--sd_hash=] [--file_name=] + [--stream_hash=] [--rowid=] [--claim_id=] [--txid=] + [--nout=] [--claim_name=] [--channel_claim_id=] + [--channel_name=] + Options: - -f, --delete_from_download_dir : delete file from download directory, - instead of just deleting blobs - --delete_all : if there are multiple matching files, - allow the deletion of multiple files. - Otherwise do not delete anything. - --sd_hash= : delete by file sd hash - --file_name : delete by file name in downloads folder - --stream_hash= : delete by file stream hash - --rowid= : delete by file row id + --delete_from_download_dir : (bool) delete file from download directory, + instead of just deleting blobs + --delete_all : (bool) if there are multiple matching files, + allow the deletion of multiple files. + Otherwise do not delete anything. + --sd_hash= : (str) delete by file sd hash + --file_name : (str) delete by file name in downloads folder + --stream_hash= : (str) delete by file stream hash + --rowid= : (int) delete by file row id + --claim_id= : (str) delete by file claim id + --txid= : (str) delete by file claim txid + --nout= : (int) delete by file claim nout + --claim_name= : (str) delete by file claim name + --channel_claim_id= : (str) delete by file channel claim id + --channel_name= : (str) delete by file channel claim name Returns: (bool) true if deletion was successful @@ -461,16 +582,26 @@ List files limited by optional filters Usage: file_list [--sd_hash=] [--file_name=] [--stream_hash=] - [--rowid=] - [-f] + [--rowid=] [--claim_id=] [--outpoint=] [--txid=] [--nout=] + [--channel_claim_id=] [--channel_name=] + [--claim_name=] [--full_status] + 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 - --rowid= : get file with matching row id - -f : full status, populate the 'message' and 'size' fields + --sd_hash= : (str) get file with matching sd hash + --file_name= : (str) get file with matching file name in the + downloads folder + --stream_hash= : (str) get file with matching stream hash + --rowid= : (int) get file with matching row id + --claim_id= : (str) get file with matching claim id + --outpoint= : (str) get file with matching claim outpoint + --txid= : (str) get file with matching claim txid + --nout= : (int) get file with matching claim nout + --channel_claim_id= : (str) get file with matching channel claim id + --channel_name= : (str) get file with matching channel name + --claim_name= : (str) get file with matching claim name + --full_status : (bool) full status, populate the + 'message' and 'size' fields Returns: (list) List of files @@ -489,9 +620,19 @@ Returns: '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 + 'total_bytes': (int) file size in bytes, None if full_status is false, + 'written_bytes': (int) written size in bytes, + 'blobs_completed': (int) num_completed, None if full_status is false, + 'blobs_in_stream': (int) None if full_status is false, + 'status': (str) downloader status, None if full_status is false, + 'claim_id': (str) None if full_status is false or if claim is not found, + 'outpoint': (str) None if full_status is false or if claim is not found, + 'txid': (str) None if full_status is false or if claim is not found, + 'nout': (int) None if full_status is false or if claim is not found, + 'metadata': (dict) None if full_status is false or if claim is not found, + 'channel_claim_id': (str) None if full_status is false or if claim is not found or signed, + 'channel_name': (str) None if full_status is false or if claim is not found or signed, + 'claim_name': (str) None if full_status is false or if claim is not found }, ] ``` @@ -506,14 +647,15 @@ Usage: [--stream_hash=] [--rowid=] [--reflector=] + 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 - --rowid= : get file with matching row id - --reflector= : reflector server, ip address or url - by default choose a server from the config + --sd_hash= : (str) get file with matching sd hash + --file_name= : (str) get file with matching file name in the + downloads folder + --stream_hash= : (str) get file with matching stream hash + --rowid= : (int) get file with matching row id + --reflector= : (str) reflector server, ip address or url + by default choose a server from the config Returns: (list) list of blobs reflected @@ -525,15 +667,17 @@ Returns: Start or stop downloading a file Usage: - file_set_status [--sd_hash=] [--file_name=] - [--stream_hash=] [--rowid=] + file_set_status ( | --status=) [--sd_hash=] + [--file_name=] [--stream_hash=] [--rowid=] + 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 - --rowid= : set status of file with matching row id + --status= : (str) one of "start" or "stop" + --sd_hash= : (str) set status of file with matching sd hash + --file_name= : (str) set status of file with matching file name in the + downloads folder + --stream_hash= : (str) set status of file with matching stream hash + --rowid= : (int) set status of file with matching row id Returns: (str) Confirmation message @@ -548,10 +692,11 @@ Usage: get [ | --file_name=] [ | --timeout=] + Options: - : specified name for the downloaded file - : download timeout in number of seconds - : path to directory where file will be saved + --uri= : (str) uri of the content to download + --file_name= : (str) specified name for the downloaded file + --timeout= : (int) download timeout in number of seconds Returns: (dict) Dictionary containing information about the stream @@ -562,39 +707,28 @@ Returns: '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, + '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 + 'total_bytes': (int) file size in bytes, None if full_status is false, + 'written_bytes': (int) written size in bytes, + 'blobs_completed': (int) num_completed, None if full_status is false, + 'blobs_in_stream': (int) None if full_status is false, + 'status': (str) downloader status, None if full_status is false, + 'claim_id': (str) claim id, + 'outpoint': (str) claim outpoint string, + 'txid': (str) claim txid, + 'nout': (int) claim nout, + 'metadata': (dict) claim metadata, + 'channel_claim_id': (str) None if claim is not signed + 'channel_name': (str) None if claim is not signed + 'claim_name': (str) claim name } ``` -## 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 @@ -603,8 +737,12 @@ Return a useful message for an API command Usage: help [ | --command=] + Options: - , --command= : command to retrieve documentation for + --command= : (str) command to retrieve documentation for + +Returns: + (str) Help message ``` ## peer_list @@ -615,8 +753,10 @@ Get peers for blob hash Usage: peer_list ( | --blob_hash=) [ | --timeout=] + Options: - , --timeout= : peer search timeout in seconds + --blob_hash= : (str) find available peers for this blob hash + --timeout= : (int) peer search timeout in seconds Returns: (list) List of contacts @@ -649,39 +789,42 @@ Usage: [--channel_name=] [--channel_id=] [--claim_address=] [--change_address=] + Options: - --metadata= : ClaimDict to associate with the claim. - --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 sources dict is provided, - it will be used. If neither are provided, an - error is raised. - --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 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 + --name=<name> : (str) name of the content + --bid=<bid> : (float) amount to back the claim + --metadata=<metadata> : (dict) ClaimDict to associate with the claim. + --file_path=<file_path> : (str) 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 sources dict is provided, + it will be used. If neither are provided, an + error is raised. + --fee=<fee> : (dict) 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> : (str) title of the publication + --description=<description> : (str) description of the publication + --author=<author> : (str) author of the publication + --language=<language> : (str) language of the publication + --license=<license> : (str) publication license + --license_url=<license_url> : (str) publication license url + --thumbnail=<thumbnail> : (str) thumbnail url + --preview=<preview> : (str) preview url + --nsfw=<nsfw> : (bool) title of the publication + --sources=<sources> : (str) {'lbry_sd_hash': sd_hash} specifies sd hash of file + --channel_name=<channel_name> : (str) name of the publisher channel name in the wallet + --channel_id=<channel_id> : (str) 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> : (str) address where the claim is sent to, if not specified + new address wil automatically be created Returns: (dict) Dictionary containing result of the claim @@ -702,6 +845,10 @@ Report a bug to slack Usage: report_bug (<message> | --message=<message>) + +Options: + --message=<message> : (str) Description of the bug + Returns: (bool) true if successful ``` @@ -712,10 +859,13 @@ Returns: Resolve given LBRY URIs Usage: - resolve [-f] (<uri> | --uri=<uri>) [<uris>...] + resolve [--force] (<uri> | --uri=<uri>) [<uris>...] + Options: - -f : force refresh and ignore cache + --force : (bool) force refresh and ignore cache + --uri=<uri> : (str) uri to resolve + --uris=<uris> : (list) uris to resolve Returns: Dictionary of results, keyed by uri @@ -735,6 +885,7 @@ Returns: 'depth': (int) claim depth, 'has_signature': (bool) included if decoded_claim 'name': (str) claim name, + 'permanent_url': (str) permanent url of the certificate claim, 'supports: (list) list of supports [{'txid': (str) txid, 'nout': (int) nout, 'amount': (float) amount}], @@ -759,6 +910,7 @@ Returns: 'depth': (int) claim depth, 'has_signature': (bool) included if decoded_claim 'name': (str) claim name, + 'permanent_url': (str) permanent url of the claim, 'channel_name': (str) channel name if claim is in a channel 'supports: (list) list of supports [{'txid': (str) txid, 'nout': (int) nout, @@ -777,10 +929,12 @@ Returns: Resolve stream info from a LBRY name Usage: - resolve_name <name> [-f] + resolve_name (<name> | --name=<name>) [--force] + Options: - -f : force refresh and do not check cache + --name=<name> : (str) the name to resolve + --force : (bool) force refresh and do not check cache Returns: (dict) Metadata dictionary from name claim, None if the name is not @@ -795,6 +949,10 @@ Get DHT routing information Usage: routing_table_get + +Options: + None + Returns: (dict) dictionary containing routing and contact information { @@ -821,6 +979,10 @@ Get daemon settings Usage: settings_get + +Options: + None + Returns: (dict) Dictionary of daemon settings See ADJUSTABLE_SETTINGS in lbrynet/conf.py for full list of settings @@ -847,34 +1009,32 @@ Usage: [--sd_download_timeout=<sd_download_timeout>] [--auto_renew_claim_height_delta=<auto_renew_claim_height_delta>] -Options: - --download_directory=<download_directory> : (str) - --data_rate=<data_rate> : (float), 0.0001 - --download_timeout=<download_timeout> : (int), 180 - --peer_port=<peer_port> : (int), 3333 - --max_key_fee=<max_key_fee> : (dict) maximum key fee for downloads, - in the format: { - "currency": <currency_symbol>, - "amount": <amount> - }. In the CLI, it must be an escaped - JSON string - Supported currency symbols: - LBC - BTC - USD - --disable_max_key_fee=<disable_max_key_fee> : (bool), False - --use_upnp=<use_upnp> : (bool), True - --run_reflector_server=<run_reflector_server> : (bool), False - --cache_time=<cache_time> : (int), 150 - --reflect_uploads=<reflect_uploads> : (bool), True - --share_usage_data=<share_usage_data> : (bool), True - --peer_search_timeout=<peer_search_timeout> : (int), 3 - --sd_download_timeout=<sd_download_timeout> : (int), 3 - --auto_renew_claim_height_delta=<auto_renew_claim_height_delta> : (int), 0 - claims set to expire within this many blocks will be - automatically renewed after startup (if set to 0, renews - will not be made automatically) +Options: + --download_directory=<download_directory> : (str) path of download directory + --data_rate=<data_rate> : (float) 0.0001 + --download_timeout=<download_timeout> : (int) 180 + --peer_port=<peer_port> : (int) 3333 + --max_key_fee=<max_key_fee> : (dict) maximum key fee for downloads, + in the format: + { + 'currency': <currency_symbol>, + 'amount': <amount> + }. + In the CLI, it must be an escaped JSON string + Supported currency symbols: LBC, USD, BTC + --disable_max_key_fee=<disable_max_key_fee> : (bool) False + --use_upnp=<use_upnp> : (bool) True + --run_reflector_server=<run_reflector_server> : (bool) False + --cache_time=<cache_time> : (int) 150 + --reflect_uploads=<reflect_uploads> : (bool) True + --share_usage_data=<share_usage_data> : (bool) True + --peer_search_timeout=<peer_search_timeout> : (int) 3 + --sd_download_timeout=<sd_download_timeout> : (int) 3 + --auto_renew_claim_height_delta=<auto_renew_claim_height_delta> : (int) 0 + claims set to expire within this many blocks will be + automatically renewed after startup (if set to 0, renews + will not be made automatically) Returns: (dict) Updated dictionary of daemon settings @@ -886,25 +1046,26 @@ Returns: Get daemon status Usage: - status [-s] [-d] + status [--session_status] [--dht_status] + Options: - -s : include session status in results - -d : include dht network and peer status + --session_status : (bool) include session status in results + --dht_status : (bool) include dht network and peer status Returns: (dict) lbrynet-daemon status { - 'lbry_id': lbry peer id, base58 - 'installation_id': installation id, base58 - 'is_running': bool - 'is_first_run': bool + 'lbry_id': lbry peer id, base58, + 'installation_id': installation id, base58, + 'is_running': bool, + 'is_first_run': bool, 'startup_status': { - 'code': status code + 'code': status code, 'message': status message }, 'connection_status': { - 'code': connection status code + 'code': connection status code, 'message': connection status message }, 'blockchain_status': { @@ -912,6 +1073,7 @@ Returns: 'blocks_behind': remote_height - local_height, 'best_blockhash': block hash of most recent block, }, + 'wallet_is_encrypted': bool, If given the session status option: 'session_status': { @@ -925,13 +1087,47 @@ Returns: 'dht_status': { 'kbps_received': current kbps receiving, 'kbps_sent': current kdps being sent, - 'total_bytes_sent': total bytes sent - 'total_bytes_received': total bytes received - 'queries_received': number of queries received per second - 'queries_sent': number of queries sent per second - 'recent_contacts': count of recently contacted peers + 'total_bytes_sent': total bytes sent, + 'total_bytes_received': total bytes received, + 'queries_received': number of queries received per second, + 'queries_sent': number of queries sent per second, + 'recent_contacts': count of recently contacted peers, 'unique_contacts': count of unique peers - } + }, + } +``` + +## stream_availability + +```text +Get stream availability for lbry uri + +Usage: + stream_availability (<uri> | --uri=<uri>) + [<search_timeout> | --search_timeout=<search_timeout>] + [<blob_timeout> | --blob_timeout=<blob_timeout>] + + +Options: + --uri=<uri> : (str) check availability for this uri + --search_timeout=<search_timeout> : (int) how long to search for peers for the blob + in the dht + --search_timeout=<blob_timeout> : (int) how long to try downloading from a peer + +Returns: + (dict) { + 'is_available': <bool>, + 'did_decode': <bool>, + 'did_resolve': <bool>, + 'is_stream': <bool>, + 'num_blobs_in_stream': <int>, + 'sd_hash': <str>, + 'sd_blob_availability': <dict> see `blob_availability`, + 'head_blob_hash': <str>, + 'head_blob_availability': <dict> see `blob_availability`, + 'use_upnp': <bool>, + 'upnp_redirect_is_set': <bool>, + 'error': <None> | <str> error message } ``` @@ -941,15 +1137,17 @@ Returns: Get estimated cost for a lbry stream Usage: - stream_cost_estimate <uri> [<size> | --size=<size>] + stream_cost_estimate (<uri> | --uri=<uri>) [<size> | --size=<size>] + Options: - <size>, --size=<size> : stream size in bytes. if provided an sd blob won't be - downloaded. + --uri=<uri> : (str) uri to use + --size=<size> : (float) 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 + resolvable ``` ## transaction_list @@ -958,35 +1156,54 @@ Returns: List transactions belonging to wallet Usage: - transaction_list [-t] + transaction_list + Options: - -t : Include claim tip information + None Returns: - (list) List of transactions, where is_tip is null by default, - and set to a boolean if include_tip_info is true + (list) List of transactions { - "claim_info": (list) claim info if in txn [{"amount": (float) claim amount, - "claim_id": (str) claim id, - "claim_name": (str) claim name, - "nout": (int) nout}], + "claim_info": (list) claim info if in txn [{ + "address": (str) address of claim, + "balance_delta": (float) bid amount, + "amount": (float) claim amount, + "claim_id": (str) claim id, + "claim_name": (str) claim name, + "nout": (int) nout + }], + "abandon_info": (list) abandon info if in txn [{ + "address": (str) address of abandoned claim, + "balance_delta": (float) returned amount, + "amount": (float) claim amount, + "claim_id": (str) claim id, + "claim_name": (str) claim name, + "nout": (int) nout + }], "confirmations": (int) number of confirmations for the txn, "date": (str) date and time of txn, "fee": (float) txn fee, - "support_info": (list) support info if in txn [{"amount": (float) support amount, - "claim_id": (str) claim id, - "claim_name": (str) claim name, - "is_tip": (null) default, - (bool) if include_tip_info is true, - "nout": (int) nout}], + "support_info": (list) support info if in txn [{ + "address": (str) address of support, + "balance_delta": (float) support amount, + "amount": (float) support amount, + "claim_id": (str) claim id, + "claim_name": (str) claim name, + "is_tip": (bool), + "nout": (int) nout + }], "timestamp": (int) timestamp, "txid": (str) txn id, - "update_info": (list) update info if in txn [{"amount": (float) updated amount, - "claim_id": (str) claim id, - "claim_name": (str) claim name, - "nout": (int) nout}], + "update_info": (list) update info if in txn [{ + "address": (str) address of claim, + "balance_delta": (float) credited/debited + "amount": (float) absolute amount, + "claim_id": (str) claim id, + "claim_name": (str) claim name, + "nout": (int) nout + }], "value": (float) value of txn } ``` @@ -999,6 +1216,10 @@ Get a decoded transaction from a txid Usage: transaction_show (<txid> | --txid=<txid>) + +Options: + --txid=<txid> : (str) txid of the transaction + Returns: (dict) JSON formatted transaction ``` @@ -1011,6 +1232,10 @@ List unspent transaction outputs Usage: utxo_list + +Options: + None + Returns: (list) List of unspent transaction outputs (UTXOs) [ @@ -1037,6 +1262,10 @@ Get lbry version information Usage: version + +Options: + None + Returns: (dict) Dictionary of lbry version information { @@ -1059,16 +1288,51 @@ Returns: Return the balance of the wallet Usage: - wallet_balance [<address> | --address=<address>] [-u] + wallet_balance [<address> | --address=<address>] [--include_unconfirmed] + Options: - <address> : If provided only the balance for this address will be given - -u : Include unconfirmed + --address=<address> : (str) If provided only the balance for this + address will be given + --include_unconfirmed : (bool) Include unconfirmed Returns: (float) amount of lbry credits in wallet ``` +## wallet_decrypt + +```text +Decrypt an encrypted wallet, this will remove the wallet password + +Usage: + wallet_decrypt + + +Options: + None + +Returns: + (bool) true if wallet is decrypted, otherwise false +``` + +## wallet_encrypt + +```text +Encrypt a wallet with a password, if the wallet is already encrypted this will update +the password + +Usage: + wallet_encrypt (<new_password> | --new_password=<new_password>) + + +Options: + --new_password=<new_password> : (str) password string to be used for encrypting wallet + +Returns: + (bool) true if wallet is decrypted, otherwise false +``` + ## wallet_is_address_mine ```text @@ -1077,6 +1341,10 @@ Checks if an address is associated with the current wallet. Usage: wallet_is_address_mine (<address> | --address=<address>) + +Options: + --address=<address> : (str) address to check + Returns: (bool) true, if address is associated with current wallet ``` @@ -1089,6 +1357,10 @@ List wallet addresses Usage: wallet_list + +Options: + None + Returns: List of wallet addresses ``` @@ -1101,6 +1373,10 @@ Generate a new wallet address Usage: wallet_new_address + +Options: + None + Returns: (str) New wallet address in base58 ``` @@ -1115,6 +1391,12 @@ Usage: (<num_addresses> | --num_addresses=<num_addresses>) (<amount> | --amount=<amount>) + +Options: + --no_broadcast : (bool) whether to broadcast or not + --num_addresses=<num_addresses> : (int) num of addresses to create + --amount=<amount> : (float) initial amount in each address + Returns: (dict) the resulting transaction ``` @@ -1127,6 +1409,10 @@ Get public key from wallet address Usage: wallet_public_key (<address> | --address=<address>) + +Options: + --address=<address> : (str) address for which to get the public key + Returns: (list) list of public keys associated with address. Could contain more than one public key if multisig. @@ -1143,7 +1429,13 @@ Usage: wallet_send (<amount> | --amount=<amount>) ((<address> | --address=<address>) | (<claim_id> | --claim_id=<claim_id>)) -Return: + +Options: + --amount=<amount> : (float) amount of credit to send + --address=<address> : (str) address to send credits to + --claim_id=<claim_id> : (float) claim_id of the claim to send to tip to + +Returns: If sending to an address: (bool) true if payment successfully scheduled @@ -1156,6 +1448,22 @@ Return: } ``` +## wallet_unlock + +```text +Unlock an encrypted wallet + +Usage: + wallet_unlock (<password> | --password=<password>) + + +Options: + --password=<password> : (str) password for unlocking wallet + +Returns: + (bool) true if wallet is unlocked, otherwise false +``` + ## wallet_unused_address ```text @@ -1165,6 +1473,10 @@ a new address if there is none. Usage: wallet_unused_address + +Options: + None + Returns: (str) Unused wallet address in base58 ``` diff --git a/docs/index.md b/docs/index.md index c6ad8010d..a0f391ca9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,14 +1,39 @@ # LBRY JSON-RPC API Documentation -## blob_announce_all +## blob_announce ```text -Announce all blobs to the DHT +Announce blobs to the DHT Args: - None + 'announce_all' (optional) : (bool) announce all the blobs possessed by user + 'blob_hash' (optional) : (str) announce a blob, specified by blob_hash + 'stream_hash' (optional) : (str) announce all blobs associated with + stream_hash + 'sd_hash' (optional) : (str) announce all blobs associated with + sd_hash and the sd_hash itself + Returns: - (str) Success/fail message + (bool) true if successful +``` + +## blob_availability + +```text +Get blob availability + +Args: + 'blob_hash' (optional) : (str) check availability for this blob hash + 'search_timeout' (optional) : (int) how long to search for peers for the blob + in the dht + 'blob_timeout' (optional) : (int) how long to try downloading from a peer + +Returns: + (dict) { + "is_available": <bool, true if blob is available from a peer from peer list> + "reachable_peers": ["<ip>:<port>"], + "unreachable_peers": ["<ip>:<port>"] + } ``` ## blob_delete @@ -17,7 +42,8 @@ Returns: Delete a blob Args: - 'blob_hash': (str) hash of blob to get + 'blob_hash' (optional) : (str) blob hash of the blob to delete + Returns: (str) Success/fail message ``` @@ -28,16 +54,18 @@ Returns: Download and return a blob Args: - 'blob_hash': (str) blob hash of blob to get - 'timeout'(optional): (int) timeout in number of seconds - 'encoding'(optional): (str) by default no attempt at decoding is made, - can be set to one of the following decoders: - 'json' - 'payment_rate_manager'(optional): if not given the default payment rate manager - will be used. supported alternative rate managers: - 'only-free' + 'blob_hash' : (str) blob hash of the blob to get + 'timeout' (optional) : (int) timeout in number of seconds + 'encoding' (optional) : (str) by default no attempt at decoding + is made, can be set to one of the + following decoders: + 'json' + 'payment_rate_manager' (optional) : (str) if not given the default payment rate + manager will be used. + supported alternative rate managers: + 'only-free' -Returns +Returns: (str) Success/Fail message or (dict) decoded data ``` @@ -47,13 +75,14 @@ Returns 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 + 'needed' (optional) : (bool) only return needed blobs + 'finished' (optional) : (bool) only return finished blobs + 'uri' (optional) : (str) filter blobs by stream in a uri + 'stream_hash' (optional) : (str) filter blobs by stream hash + 'sd_hash' (optional) : (str) filter blobs by sd hash + 'page_size' (optional) : (int) results page size + 'page' (optional) : (int) page of results to return + Returns: (list) List of blob hashes ``` @@ -64,7 +93,8 @@ Returns: Reflects all saved blobs Args: - None + None + Returns: (bool) true if successful ``` @@ -75,28 +105,58 @@ Returns: Get contents of a block Args: - 'blockhash': (str) hash of the block to look up + 'blockhash' : (str) hash of the block to look up + 'height' : (int) height of the block to look up + Returns: (dict) Requested block ``` -## channel_list_mine +## channel_export ```text -Get my channels +Export serialized channel signing information for a given certificate claim id + +Args: + 'claim_id' : (str) Claim ID to export information about Returns: - (list) ClaimDict + (str) Serialized certificate information +``` + +## channel_import + +```text +Import serialized channel signing information (to allow signing new claims to the channel) + +Args: + 'serialized_certificate_info' (optional) : (str) certificate info + +Returns: + (dict) Result dictionary +``` + +## channel_list + +```text +Get certificate claim infos for channels that can be published to + +Args: + None + +Returns: + (list) ClaimDict, includes 'is_mine' field to indicate if the certificate claim + is in the wallet. ``` ## channel_new ```text -Generate a publisher key and create a new certificate claim +Generate a publisher key and create a new '@' prefixed certificate claim Args: - 'channel_name': (str) '@' prefixed name - 'amount': (float) amount to claim name + 'channel_name' : (str) name of the channel prefixed with '@' + 'amount' : (float) bid amount on the channel Returns: (dict) Dictionary containing result of the claim @@ -115,8 +175,11 @@ Returns: Abandon a name and reclaim credits from the claim Args: - 'claim_id': (str) claim_id of claim -Return: + 'claim_id' (optional) : (str) claim_id of the claim to abandon + 'txid' (optional) : (str) txid of the claim to abandon + 'nout' (optional) : (int) nout of the claim to abandon + +Returns: (dict) Dictionary containing result of the claim { txid : (str) txid of resulting transaction @@ -127,11 +190,12 @@ Return: ## claim_list ```text -Get claims for a name +List current claims and information about them for a given name Args: - 'name': (str) search for claims on this name -Returns + 'name' : (str) name of the claim to list info about + +Returns: (dict) State of claims assigned for the name { 'claims': (list) list of claims for the name @@ -144,6 +208,7 @@ Returns 'height': (int) height of block containing the claim 'txid': (str) txid of the claim 'nout': (int) nout of the claim + 'permanent_url': (str) permanent url of the claim, 'supports': (list) a list of supports attached to the claim 'value': (str) the value of the claim }, @@ -153,14 +218,65 @@ Returns } ``` +## claim_list_by_channel + +```text +Get paginated claims in a channel specified by a channel uri + +Args: + 'uri' : (str) uri of the channel + 'uris' (optional) : (list) uris of the channel + 'page' (optional) : (int) which page of results to return where page 1 is the first + page, defaults to no pages + 'page_size' (optional) : (int) number of results in a page, default of 10 + +Returns: + { + resolved channel uri: { + If there was an error: + 'error': (str) error message + + 'claims_in_channel': the total number of results for the channel, + + If a page of results was requested: + 'returned_page': page number returned, + 'claims_in_channel': [ + { + 'absolute_channel_position': (int) claim index number in sorted list of + claims which assert to be part of the + 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': (str) txid, + 'nout': (int) nout, + 'amount': (float) amount}], + 'txid': (str) claim txid, + 'nout': (str) claim nout, + 'signature_is_valid': (bool), included if has_signature, + 'value': ClaimDict if decoded, otherwise hex string + } + ], + } + } +``` + ## claim_list_mine ```text List my name claims Args: - None -Returns + None + +Returns: (list) List of name claims owned by user [ { @@ -175,6 +291,7 @@ Returns '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 + 'permanent_url': (str) permanent url of the claim, 'txid': (str) txid of the cliam 'nout': (int) nout of the claim 'value': (str) value of the claim @@ -188,10 +305,11 @@ Returns Support a name claim Args: - 'name': (str) Name of claim - 'claim_id': (str) claim ID of claim to support - 'amount': (float) amount to support by -Return: + 'name' : (str) name of the claim to support + 'claim_id' : (str) claim_id of the claim to support + 'amount' : (float) amount of support + +Returns: (dict) Dictionary containing result of the claim { txid : (str) txid of resulting support claim @@ -200,19 +318,66 @@ Return: } ``` +## claim_renew + +```text +Renew claim(s) or support(s) + +Args: + 'outpoint' : (str) outpoint of the claim to renew + 'height' : (str) update claims expiring before or at this block height + +Returns: + (dict) Dictionary where key is the the original claim's outpoint and + value is the result of the renewal + { + outpoint:{ + + '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_send_to_address + +```text +Send a name claim to an address + +Args: + 'claim_id' : (str) claim_id to send + 'address' : (str) address to send the claim to + 'amount' (optional) : (int) Amount of credits to claim name for, defaults to the current amount + on the claim + +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_show ```text -Resolve claim info from a LBRY name +Resolve claim info from txid/nout or with claim ID Args: - 'name': (str) name to look up, do not include lbry:// prefix - 'txid'(optional): (str) if specified, look for claim with this txid - 'nout'(optional): (int) if specified, look for claim with this nout - 'claim_id'(optional): (str) if specified, look for claim with this claim_id + 'txid' (optional) : (str) look for claim with this txid, nout must + also be specified + 'nout' (optional) : (int) look for claim with this nout, txid must + also be specified + 'claim_id' (optional) : (str) look for claim with this claim id + Returns: - (dict) Dictionary containing claim info, (bool) false if claim is not - resolvable + (dict) Dictionary containing claim info as below, { 'txid': (str) txid of claim @@ -223,6 +388,28 @@ Returns: 'claim_id': (str) claim ID of claim 'supports': (list) list of supports associated with claim } + + if claim cannot be resolved, dictionary as below will be returned + + { + 'error': (str) reason for error + } +``` + +## cli_test_command + +```text +This command is only for testing the CLI argument parsing +Args: + 'a_arg' (optional) : a arg + 'b_arg' (optional) : b arg + 'pos_arg' : pos arg + 'pos_args' (optional) : pos args + 'pos_arg2' (optional) : pos arg 2 + 'pos_arg3' (optional) : pos arg 3 + +Returns: + pos args ``` ## commands @@ -230,6 +417,9 @@ Returns: ```text Return a list of available commands +Args: + None + Returns: (list) list of available commands ``` @@ -239,42 +429,35 @@ Returns: ```text Stop lbrynet-daemon +Args: + None + Returns: (string) Shutdown message ``` -## descriptor_get - -```text -Download and return a sd blob - -Args: - 'sd_hash': (str) hash of sd blob - 'timeout'(optional): (int) timeout in number of seconds - 'payment_rate_manager'(optional): (str) 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 -``` - ## file_delete ```text -Delete a lbry file +Delete a LBRY file Args: - 'name' (optional): (str) delete file by lbry name, - 'sd_hash' (optional): (str) delete file by sd hash, - 'file_name' (optional): (str) delete file by the name in the downloads folder, - 'stream_hash' (optional): (str) delete file by stream hash, - 'claim_id' (optional): (str) delete file by claim ID, - 'outpoint' (optional): (str) delete file by claim outpoint, - 'rowid': (optional): (int) delete file by rowid in the file manager - 'delete_target_file' (optional): (bool) delete file from downloads folder, - defaults to true if false only the blobs and - db entries will be deleted + 'delete_from_download_dir' (optional) : (bool) delete file from download directory, + instead of just deleting blobs + 'delete_all' (optional) : (bool) if there are multiple matching files, + allow the deletion of multiple files. + Otherwise do not delete anything. + 'sd_hash' (optional) : (str) delete by file sd hash + 'file_name' (optional) : (str) delete by file name in downloads folder + 'stream_hash' (optional) : (str) delete by file stream hash + 'rowid' (optional) : (int) delete by file row id + 'claim_id' (optional) : (str) delete by file claim id + 'txid' (optional) : (str) delete by file claim txid + 'nout' (optional) : (int) delete by file claim nout + 'claim_name' (optional) : (str) delete by file claim name + 'channel_claim_id' (optional) : (str) delete by file channel claim id + 'channel_name' (optional) : (str) delete by file channel claim name + Returns: (bool) true if deletion was successful ``` @@ -285,14 +468,20 @@ Returns: List files limited by optional filters Args: - 'name' (optional): (str) filter files by lbry name, - 'sd_hash' (optional): (str) filter files by sd hash, - 'file_name' (optional): (str) filter files by the name in the downloads folder, - 'stream_hash' (optional): (str) filter files by stream hash, - 'claim_id' (optional): (str) filter files by claim id, - 'outpoint' (optional): (str) filter files by claim outpoint, - 'rowid' (optional): (int) filter files by internal row id, - 'full_status': (optional): (bool) if true populate the 'message' and 'size' fields + 'sd_hash' (optional) : (str) get file with matching sd hash + 'file_name' (optional) : (str) get file with matching file name in the + downloads folder + 'stream_hash' (optional) : (str) get file with matching stream hash + 'rowid' (optional) : (int) get file with matching row id + 'claim_id' (optional) : (str) get file with matching claim id + 'outpoint' (optional) : (str) get file with matching claim outpoint + 'txid' (optional) : (str) get file with matching claim txid + 'nout' (optional) : (int) get file with matching claim nout + 'channel_claim_id' (optional) : (str) get file with matching channel claim id + 'channel_name' (optional) : (str) get file with matching channel name + 'claim_name' (optional) : (str) get file with matching claim name + 'full_status' (optional) : (bool) full status, populate the + 'message' and 'size' fields Returns: (list) List of files @@ -308,30 +497,57 @@ Returns: '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 + 'total_bytes': (int) file size in bytes, None if full_status is false, + 'written_bytes': (int) written size in bytes, + 'blobs_completed': (int) num_completed, None if full_status is false, + 'blobs_in_stream': (int) None if full_status is false, + 'status': (str) downloader status, None if full_status is false, + 'claim_id': (str) None if full_status is false or if claim is not found, + 'outpoint': (str) None if full_status is false or if claim is not found, + 'txid': (str) None if full_status is false or if claim is not found, + 'nout': (int) None if full_status is false or if claim is not found, + 'metadata': (dict) None if full_status is false or if claim is not found, + 'channel_claim_id': (str) None if full_status is false or if claim is not found or signed, + 'channel_name': (str) None if full_status is false or if claim is not found or signed, + 'claim_name': (str) None if full_status is false or if claim is not found }, ] ``` +## file_reflect + +```text +Reflect all the blobs in a file matching the filter criteria + +Args: + 'sd_hash' (optional) : (str) get file with matching sd hash + 'file_name' (optional) : (str) get file with matching file name in the + downloads folder + 'stream_hash' (optional) : (str) get file with matching stream hash + 'rowid' (optional) : (int) get file with matching row id + 'reflector' (optional) : (str) reflector server, ip address or url + by default choose a server from the config + +Returns: + (list) list of blobs reflected +``` + ## file_set_status ```text Start or stop downloading a file Args: - 'status': (str) "start" or "stop" - 'name' (optional): (str) start file by lbry name, - 'sd_hash' (optional): (str) start file by the hash in the name claim, - 'file_name' (optional): (str) start file by its name in the downloads folder, + 'status' : (str) one of "start" or "stop" + 'sd_hash' (optional) : (str) set status of file with matching sd hash + 'file_name' (optional) : (str) set status of file with matching file name in the + downloads folder + 'stream_hash' (optional) : (str) set status of file with matching stream hash + 'rowid' (optional) : (int) set status of file with matching row id + Returns: (str) Confirmation message ``` @@ -342,10 +558,10 @@ Returns: Download stream from a LBRY name. Args: - 'uri': (str) lbry uri to download - 'file_name'(optional): (str) a user specified name for the downloaded file - 'timeout'(optional): (int) download timeout in number of seconds - 'download_directory'(optional): (str) path to directory where file will be saved + 'uri' (optional) : (str) uri of the content to download + 'file_name' (optional) : (str) specified name for the downloaded file + 'timeout' (optional) : (int) download timeout in number of seconds + Returns: (dict) Dictionary containing information about the stream { @@ -355,46 +571,38 @@ Returns: '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, + '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 + 'total_bytes': (int) file size in bytes, None if full_status is false, + 'written_bytes': (int) written size in bytes, + 'blobs_completed': (int) num_completed, None if full_status is false, + 'blobs_in_stream': (int) None if full_status is false, + 'status': (str) downloader status, None if full_status is false, + 'claim_id': (str) claim id, + 'outpoint': (str) claim outpoint string, + 'txid': (str) claim txid, + 'nout': (int) claim nout, + 'metadata': (dict) claim metadata, + 'channel_claim_id': (str) None if claim is not signed + 'channel_name': (str) None if claim is not signed + 'claim_name': (str) claim name } ``` -## get_availability - -```text -Get stream availability for lbry uri - -Args: - 'uri' : (str) lbry uri - 'sd_timeout' (optional): (int) sd blob download timeout - 'peer_timeout' (optional): (int) how long to look for peers - -Returns: - (float) Peers per blob / total blobs -``` - ## help ```text Return a useful message for an API command Args: - 'command'(optional): (str) command to retrieve documentation for + 'command' (optional) : (str) command to retrieve documentation for + Returns: - (str) if given a command, returns documentation about that command - otherwise returns general help message + (str) Help message ``` ## peer_list @@ -403,8 +611,9 @@ Returns: Get peers for blob hash Args: - 'blob_hash': (str) blob hash - 'timeout'(optional): (int) peer search timeout in seconds + 'blob_hash' : (str) find available peers for this blob hash + 'timeout' (optional) : (int) peer search timeout in seconds + Returns: (list) List of contacts ``` @@ -420,7 +629,7 @@ Fields required in the final Metadata are: 'description' 'author' 'language' - 'license', + 'license' 'nsfw' Metadata can be set by either using the metadata argument or by setting individual arguments @@ -428,29 +637,40 @@ fee, title, description, author, language, license, license_url, thumbnail, prev or sources. Individual arguments will overwrite the fields specified in metadata argument. Args: - 'name': (str) name to be claimed - 'bid': (float) amount of credits to commit in this claim, - 'metadata'(optional): (dict) Metadata to associate with the claim. - 'file_path'(optional): (str) 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'(optional): (dict) Dictionary representing key fee to download content: - {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'(optional): (str) title of the file - 'description'(optional): (str) description of the file - 'author'(optional): (str) author of the file - 'language'(optional): (str), language code - 'license'(optional): (str) license for the file - 'license_url'(optional): (str) URL to license - 'thumbnail'(optional): (str) thumbnail URL for the file - 'preview'(optional): (str) preview URL for the file - 'nsfw'(optional): (bool) True if not safe for work - 'sources'(optional): (dict){'lbry_sd_hash':sd_hash} specifies sd hash of file - 'channel_name' (optional): (str) name of the publisher channel + 'name' : (str) name of the content + 'bid' : (float) amount to back the claim + 'metadata' (optional) : (dict) ClaimDict to associate with the claim. + 'file_path' (optional) : (str) 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 sources dict is provided, + it will be used. If neither are provided, an + error is raised. + 'fee' (optional) : (dict) 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' (optional) : (str) title of the publication + 'description' (optional) : (str) description of the publication + 'author' (optional) : (str) author of the publication + 'language' (optional) : (str) language of the publication + 'license' (optional) : (str) publication license + 'license_url' (optional) : (str) publication license url + 'thumbnail' (optional) : (str) thumbnail url + 'preview' (optional) : (str) preview url + 'nsfw' (optional) : (bool) title of the publication + 'sources' (optional) : (str) {'lbry_sd_hash': sd_hash} specifies sd hash of file + 'channel_name' (optional) : (str) name of the publisher channel name in the wallet + 'channel_id' (optional) : (str) 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' (optional) : (str) address where the claim is sent to, if not specified + new address wil automatically be created Returns: (dict) Dictionary containing result of the claim @@ -463,24 +683,14 @@ Returns: } ``` -## reflect - -```text -Reflect a stream - -Args: - 'sd_hash': (str) sd_hash of lbry file -Returns: - (bool) true if successful -``` - ## report_bug ```text Report a bug to slack Args: - 'message': (str) message to send + 'message' : (str) Description of the bug + Returns: (bool) true if successful ``` @@ -488,35 +698,21 @@ Returns: ## resolve ```text -Resolve a LBRY URI +Resolve given LBRY URIs Args: - 'uri': (str) uri to download + 'force' (optional) : (bool) force refresh and ignore cache + 'uri' : (str) uri to resolve + 'uris' (optional) : (list) uris to resolve + 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': [ - { + Dictionary of results, keyed by uri + '<uri>': { + If a resolution error occurs: + 'error': Error message + + If the 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, @@ -527,36 +723,41 @@ Returns: '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}], + 'permanent_url': (str) permanent url of the certificate claim, + 'supports: (list) list of supports [{'txid': (str) txid, + 'nout': (int) nout, + 'amount': (float) 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 the uri resolves to a channel: + 'claims_in_channel': (int) number of claims in the channel, + + If the 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, + 'permanent_url': (str) permanent url of the claim, + 'channel_name': (str) channel name if claim is in a channel + 'supports: (list) list of supports [{'txid': (str) txid, + 'nout': (int) nout, + 'amount': (float) 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 - } } ``` @@ -566,22 +767,38 @@ Returns: Resolve stream info from a LBRY name Args: - 'name': (str) name to look up, do not include lbry:// prefix + 'name' : (str) the name to resolve + 'force' (optional) : (bool) 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 +## routing_table_get ```text -Send credits to an address +Get DHT routing information Args: - 'amount': (float) the amount to send - 'address': (str) the address of the recipient in base58 + None + Returns: - (bool) true if payment successfully scheduled + (dict) dictionary containing routing and contact information + { + "buckets": { + <bucket index>: [ + { + "address": (str) peer address, + "node_id": (str) peer node id, + "blobs": (list) blob hashes announced by peer + } + ] + }, + "contacts": (list) contact node ids, + "blob_hashes": (list) all of the blob hashes stored by peers in the list of buckets, + "node_id": (str) the local dht node id + } ``` ## settings_get @@ -589,6 +806,9 @@ Returns: ```text Get daemon settings +Args: + None + Returns: (dict) Dictionary of daemon settings See ADJUSTABLE_SETTINGS in lbrynet/conf.py for full list of settings @@ -600,17 +820,31 @@ Returns: Set daemon settings Args: - 'run_on_startup': (bool) currently not supported - 'data_rate': (float) data rate, - 'max_key_fee': (float) maximum key fee, - 'disable_max_key_fee': (bool) true to disable max_key_fee check, - 'download_directory': (str) path of where files are downloaded, - 'peer_port': (int) port through which daemon should connect, - '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 + 'download_directory' (optional) : (str) path of download directory + 'data_rate' (optional) : (float) 0.0001 + 'download_timeout' (optional) : (int) 180 + 'peer_port' (optional) : (int) 3333 + 'max_key_fee' (optional) : (dict) maximum key fee for downloads, + in the format: + { + 'currency': <currency_symbol>, + 'amount': <amount> + }. + In the CLI, it must be an escaped JSON string + Supported currency symbols: LBC, USD, BTC + 'disable_max_key_fee' (optional) : (bool) False + 'use_upnp' (optional) : (bool) True + 'run_reflector_server' (optional) : (bool) False + 'cache_time' (optional) : (int) 150 + 'reflect_uploads' (optional) : (bool) True + 'share_usage_data' (optional) : (bool) True + 'peer_search_timeout' (optional) : (int) 3 + 'sd_download_timeout' (optional) : (int) 3 + 'auto_renew_claim_height_delta' (optional) : (int) 0 + claims set to expire within this many blocks will be + automatically renewed after startup (if set to 0, renews + will not be made automatically) + Returns: (dict) Updated dictionary of daemon settings ``` @@ -618,13 +852,82 @@ Returns: ## status ```text -Return daemon status +Get daemon status Args: - 'session_status' (optional): (bool) true to return session status, - default is false + 'session_status' (optional) : (bool) include session status in results + 'dht_status' (optional) : (bool) include dht network and peer status + Returns: - (dict) Daemon status dictionary + (dict) lbrynet-daemon status + { + 'lbry_id': lbry peer id, base58, + 'installation_id': installation id, base58, + 'is_running': bool, + 'is_first_run': bool, + 'startup_status': { + 'code': status code, + 'message': status message + }, + 'connection_status': { + 'code': connection status code, + 'message': connection status message + }, + 'blockchain_status': { + 'blocks': local blockchain height, + 'blocks_behind': remote_height - local_height, + 'best_blockhash': block hash of most recent block, + }, + 'wallet_is_encrypted': bool, + + If given the session status option: + 'session_status': { + 'managed_blobs': count of blobs in the blob manager, + 'managed_streams': count of streams in the file manager + 'announce_queue_size': number of blobs currently queued to be announced + 'should_announce_blobs': number of blobs that should be announced + } + + If given the dht status option: + 'dht_status': { + 'kbps_received': current kbps receiving, + 'kbps_sent': current kdps being sent, + 'total_bytes_sent': total bytes sent, + 'total_bytes_received': total bytes received, + 'queries_received': number of queries received per second, + 'queries_sent': number of queries sent per second, + 'recent_contacts': count of recently contacted peers, + 'unique_contacts': count of unique peers + }, + } +``` + +## stream_availability + +```text +Get stream availability for lbry uri + +Args: + 'uri' : (str) check availability for this uri + 'search_timeout' (optional) : (int) how long to search for peers for the blob + in the dht + 'search_timeout' (optional) : (int) how long to try downloading from a peer + +Returns: + (dict) { + 'is_available': <bool>, + 'did_decode': <bool>, + 'did_resolve': <bool>, + 'is_stream': <bool>, + 'num_blobs_in_stream': <int>, + 'sd_hash': <str>, + 'sd_blob_availability': <dict> see `blob_availability`, + 'head_blob_hash': <str>, + 'head_blob_availability': <dict> see `blob_availability`, + 'use_upnp': <bool>, + 'upnp_redirect_is_set': <bool>, + 'error': <None> | <str> error message + } ``` ## stream_cost_estimate @@ -633,12 +936,13 @@ Returns: Get estimated cost for a lbry stream Args: - 'name': (str) lbry name - 'size' (optional): (int) stream size, in bytes. if provided an sd blob - won't be downloaded. + 'uri' : (str) uri to use + 'size' (optional) : (float) 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 + resolvable ``` ## transaction_list @@ -647,9 +951,52 @@ Returns: List transactions belonging to wallet Args: - None + None + Returns: (list) List of transactions + + { + "claim_info": (list) claim info if in txn [{ + "address": (str) address of claim, + "balance_delta": (float) bid amount, + "amount": (float) claim amount, + "claim_id": (str) claim id, + "claim_name": (str) claim name, + "nout": (int) nout + }], + "abandon_info": (list) abandon info if in txn [{ + "address": (str) address of abandoned claim, + "balance_delta": (float) returned amount, + "amount": (float) claim amount, + "claim_id": (str) claim id, + "claim_name": (str) claim name, + "nout": (int) nout + }], + "confirmations": (int) number of confirmations for the txn, + "date": (str) date and time of txn, + "fee": (float) txn fee, + "support_info": (list) support info if in txn [{ + "address": (str) address of support, + "balance_delta": (float) support amount, + "amount": (float) support amount, + "claim_id": (str) claim id, + "claim_name": (str) claim name, + "is_tip": (bool), + "nout": (int) nout + }], + "timestamp": (int) timestamp, + "txid": (str) txn id, + "update_info": (list) update info if in txn [{ + "address": (str) address of claim, + "balance_delta": (float) credited/debited + "amount": (float) absolute amount, + "claim_id": (str) claim id, + "claim_name": (str) claim name, + "nout": (int) nout + }], + "value": (float) value of txn + } ``` ## transaction_show @@ -658,18 +1005,46 @@ Returns: Get a decoded transaction from a txid Args: - 'txid': (str) txid of transaction + 'txid' : (str) txid of the transaction + Returns: (dict) JSON formatted transaction ``` +## utxo_list + +```text +List unspent transaction outputs + +Args: + None + +Returns: + (list) List of unspent transaction outputs (UTXOs) + [ + { + "address": (str) the output address + "amount": (float) unspent amount + "height": (int) block height + "is_claim": (bool) is the tx a claim + "is_coinbase": (bool) is the tx a coinbase tx + "is_support": (bool) is the tx a support + "is_update": (bool) is the tx an update + "nout": (int) nout of the output + "txid": (str) txid of the output + }, + ... + ] +``` + ## version ```text Get lbry version information Args: - None + None + Returns: (dict) Dictionary of lbry version information { @@ -692,21 +1067,47 @@ Returns: Return the balance of the wallet Args: - 'address' (optional): If address is provided only that balance will be given - 'include_unconfirmed' (optional): If set unconfirmed balance will be included in - the only takes effect when address is also provided. + 'address' (optional) : (str) If provided only the balance for this + address will be given + 'include_unconfirmed' (optional) : (bool) Include unconfirmed Returns: (float) amount of lbry credits in wallet ``` +## wallet_decrypt + +```text +Decrypt an encrypted wallet, this will remove the wallet password + +Args: + None + +Returns: + (bool) true if wallet is decrypted, otherwise false +``` + +## wallet_encrypt + +```text +Encrypt a wallet with a password, if the wallet is already encrypted this will update +the password + +Args: + 'new_password' : (str) password string to be used for encrypting wallet + +Returns: + (bool) true if wallet is decrypted, otherwise false +``` + ## wallet_is_address_mine ```text Checks if an address is associated with the current wallet. Args: - 'address': (str) address to check in base58 + 'address' : (str) address to check + Returns: (bool) true, if address is associated with current wallet ``` @@ -717,7 +1118,8 @@ Returns: List wallet addresses Args: - None + None + Returns: List of wallet addresses ``` @@ -728,23 +1130,76 @@ Returns: Generate a new wallet address Args: - None + None + Returns: (str) New wallet address in base58 ``` +## wallet_prefill_addresses + +```text +Create new addresses, each containing `amount` credits + +Args: + 'no_broadcast' (optional) : (bool) whether to broadcast or not + 'num_addresses' : (int) num of addresses to create + 'amount' : (float) initial amount in each address + +Returns: + (dict) the resulting transaction +``` + ## wallet_public_key ```text Get public key from wallet address Args: - 'address': (str) wallet address in base58 + 'address' : (str) address for which to get the public key + Returns: (list) list of public keys associated with address. Could contain more than one public key if multisig. ``` +## wallet_send + +```text +Send credits. If given an address, send credits to it. If given a claim id, send a tip +to the owner of a claim specified by uri. A tip is a claim support where the recipient +of the support is the claim address for the claim being supported. + +Args: + 'amount' : (float) amount of credit to send + 'address' : (str) address to send credits to + 'claim_id' : (float) claim_id of the claim to send to tip to + +Returns: + If sending to an address: + (bool) true if payment successfully scheduled + + If sending a claim tip: + (dict) Dictionary containing the result of the support + { + txid : (str) txid of resulting support claim + nout : (int) nout of the resulting support claim + fee : (float) fee paid for the transaction + } +``` + +## wallet_unlock + +```text +Unlock an encrypted wallet + +Args: + 'password' : (str) password for unlocking wallet + +Returns: + (bool) true if wallet is unlocked, otherwise false +``` + ## wallet_unused_address ```text @@ -752,7 +1207,8 @@ Return an address containing no balance, will create a new address if there is none. Args: - None + None + Returns: (str) Unused wallet address in base58 ``` diff --git a/lbrynet/daemon/Daemon.py b/lbrynet/daemon/Daemon.py index afad31566..419409af2 100644 --- a/lbrynet/daemon/Daemon.py +++ b/lbrynet/daemon/Daemon.py @@ -997,17 +997,16 @@ class Daemon(AuthJSONRPCServer): ############################################################################ @defer.inlineCallbacks - @AuthJSONRPCServer.flags(session_status="-s", dht_status="-d") def jsonrpc_status(self, session_status=False, dht_status=False): """ Get daemon status Usage: - status [-s] [-d] + status [--session_status] [--dht_status] Options: - -s : include session status in results - -d : include dht network and peer status + --session_status : (bool) include session status in results + --dht_status : (bool) include dht network and peer status Returns: (dict) lbrynet-daemon status @@ -1107,6 +1106,9 @@ class Daemon(AuthJSONRPCServer): Usage: version + Options: + None + Returns: (dict) Dictionary of lbry version information { @@ -1135,6 +1137,9 @@ class Daemon(AuthJSONRPCServer): Usage: report_bug (<message> | --message=<message>) + Options: + --message=<message> : (str) Description of the bug + Returns: (bool) true if successful """ @@ -1155,6 +1160,9 @@ class Daemon(AuthJSONRPCServer): Usage: settings_get + Options: + None + Returns: (dict) Dictionary of daemon settings See ADJUSTABLE_SETTINGS in lbrynet/conf.py for full list of settings @@ -1184,29 +1192,27 @@ class Daemon(AuthJSONRPCServer): [--auto_renew_claim_height_delta=<auto_renew_claim_height_delta>] Options: - --download_directory=<download_directory> : (str) - --data_rate=<data_rate> : (float), 0.0001 - --download_timeout=<download_timeout> : (int), 180 - --peer_port=<peer_port> : (int), 3333 - --max_key_fee=<max_key_fee> : (dict) maximum key fee for downloads, - in the format: { - "currency": <currency_symbol>, - "amount": <amount> - }. In the CLI, it must be an escaped - JSON string - Supported currency symbols: - LBC - BTC - USD - --disable_max_key_fee=<disable_max_key_fee> : (bool), False - --use_upnp=<use_upnp> : (bool), True - --run_reflector_server=<run_reflector_server> : (bool), False - --cache_time=<cache_time> : (int), 150 - --reflect_uploads=<reflect_uploads> : (bool), True - --share_usage_data=<share_usage_data> : (bool), True - --peer_search_timeout=<peer_search_timeout> : (int), 3 - --sd_download_timeout=<sd_download_timeout> : (int), 3 - --auto_renew_claim_height_delta=<auto_renew_claim_height_delta> : (int), 0 + --download_directory=<download_directory> : (str) path of download directory + --data_rate=<data_rate> : (float) 0.0001 + --download_timeout=<download_timeout> : (int) 180 + --peer_port=<peer_port> : (int) 3333 + --max_key_fee=<max_key_fee> : (dict) maximum key fee for downloads, + in the format: + { + 'currency': <currency_symbol>, + 'amount': <amount> + }. + In the CLI, it must be an escaped JSON string + Supported currency symbols: LBC, USD, BTC + --disable_max_key_fee=<disable_max_key_fee> : (bool) False + --use_upnp=<use_upnp> : (bool) True + --run_reflector_server=<run_reflector_server> : (bool) False + --cache_time=<cache_time> : (int) 150 + --reflect_uploads=<reflect_uploads> : (bool) True + --share_usage_data=<share_usage_data> : (bool) True + --peer_search_timeout=<peer_search_timeout> : (int) 3 + --sd_download_timeout=<sd_download_timeout> : (int) 3 + --auto_renew_claim_height_delta=<auto_renew_claim_height_delta> : (int) 0 claims set to expire within this many blocks will be automatically renewed after startup (if set to 0, renews will not be made automatically) @@ -1227,7 +1233,10 @@ class Daemon(AuthJSONRPCServer): help [<command> | --command=<command>] Options: - <command>, --command=<command> : command to retrieve documentation for + --command=<command> : (str) command to retrieve documentation for + + Returns: + (str) Help message """ if command is None: @@ -1256,22 +1265,25 @@ class Daemon(AuthJSONRPCServer): Usage: commands + Options: + None + Returns: (list) list of available commands """ return self._render_response(sorted([command for command in self.callable_methods.keys()])) - @AuthJSONRPCServer.flags(include_unconfirmed='-u') def jsonrpc_wallet_balance(self, address=None, include_unconfirmed=False): """ Return the balance of the wallet Usage: - wallet_balance [<address> | --address=<address>] [-u] + wallet_balance [<address> | --address=<address>] [--include_unconfirmed] Options: - <address> : If provided only the balance for this address will be given - -u : Include unconfirmed + --address=<address> : (str) If provided only the balance for this + address will be given + --include_unconfirmed : (bool) Include unconfirmed Returns: (float) amount of lbry credits in wallet @@ -1288,7 +1300,10 @@ class Daemon(AuthJSONRPCServer): Unlock an encrypted wallet Usage: - wallet_unlock (<password>) + wallet_unlock (<password> | --password=<password>) + + Options: + --password=<password> : (str) password for unlocking wallet Returns: (bool) true if wallet is unlocked, otherwise false @@ -1312,6 +1327,9 @@ class Daemon(AuthJSONRPCServer): Usage: wallet_decrypt + Options: + None + Returns: (bool) true if wallet is decrypted, otherwise false """ @@ -1327,7 +1345,10 @@ class Daemon(AuthJSONRPCServer): the password Usage: - wallet_encrypt (<new_password>) + wallet_encrypt (<new_password> | --new_password=<new_password>) + + Options: + --new_password=<new_password> : (str) password string to be used for encrypting wallet Returns: (bool) true if wallet is decrypted, otherwise false @@ -1345,6 +1366,9 @@ class Daemon(AuthJSONRPCServer): Usage: daemon_stop + Options: + None + Returns: (string) Shutdown message """ @@ -1355,7 +1379,6 @@ class Daemon(AuthJSONRPCServer): defer.returnValue(response) @defer.inlineCallbacks - @AuthJSONRPCServer.flags(full_status='-f') def jsonrpc_file_list(self, **kwargs): """ List files limited by optional filters @@ -1364,22 +1387,23 @@ class Daemon(AuthJSONRPCServer): file_list [--sd_hash=<sd_hash>] [--file_name=<file_name>] [--stream_hash=<stream_hash>] [--rowid=<rowid>] [--claim_id=<claim_id>] [--outpoint=<outpoint>] [--txid=<txid>] [--nout=<nout>] [--channel_claim_id=<channel_claim_id>] [--channel_name=<channel_name>] - [--claim_name=<claim_name>] [-f] + [--claim_name=<claim_name>] [--full_status] Options: - --sd_hash=<sd_hash> : get file with matching sd hash - --file_name=<file_name> : get file with matching file name in the + --sd_hash=<sd_hash> : (str) get file with matching sd hash + --file_name=<file_name> : (str) get file with matching file name in the downloads folder - --stream_hash=<stream_hash> : get file with matching stream hash - --rowid=<rowid> : get file with matching row id - --claim_id=<claim_id> : get file with matching claim id - --outpoint=<outpoint> : get file with matching claim outpoint - --txid=<txid> : get file with matching claim txid - --nout=<nout> : get file with matching claim nout - --channel_claim_id=<channel_claim_id> : get file with matching channel claim id - --channel_name=<channel_name> : get file with matching channel name - --claim_name=<claim_name> : get file with matching claim name - -f : full status, populate the 'message' and 'size' fields + --stream_hash=<stream_hash> : (str) get file with matching stream hash + --rowid=<rowid> : (int) get file with matching row id + --claim_id=<claim_id> : (str) get file with matching claim id + --outpoint=<outpoint> : (str) get file with matching claim outpoint + --txid=<txid> : (str) get file with matching claim txid + --nout=<nout> : (int) get file with matching claim nout + --channel_claim_id=<channel_claim_id> : (str) get file with matching channel claim id + --channel_name=<channel_name> : (str) get file with matching channel name + --claim_name=<claim_name> : (str) get file with matching claim name + --full_status : (bool) full status, populate the + 'message' and 'size' fields Returns: (list) List of files @@ -1420,16 +1444,16 @@ class Daemon(AuthJSONRPCServer): defer.returnValue(response) @defer.inlineCallbacks - @AuthJSONRPCServer.flags(force='-f') def jsonrpc_resolve_name(self, name, force=False): """ Resolve stream info from a LBRY name Usage: - resolve_name <name> [-f] + resolve_name (<name> | --name=<name>) [--force] Options: - -f : force refresh and do not check cache + --name=<name> : (str) the name to resolve + --force : (bool) force refresh and do not check cache Returns: (dict) Metadata dictionary from name claim, None if the name is not @@ -1454,11 +1478,11 @@ class Daemon(AuthJSONRPCServer): [<claim_id> | --claim_id=<claim_id>] Options: - <txid>, --txid=<txid> : look for claim with this txid, nout must - also be specified - <nout>, --nout=<nout> : look for claim with this nout, txid must - also be specified - <claim_id>, --claim_id=<claim_id> : look for claim with this claim id + --txid=<txid> : (str) look for claim with this txid, nout must + also be specified + --nout=<nout> : (int) look for claim with this nout, txid must + also be specified + --claim_id=<claim_id> : (str) look for claim with this claim id Returns: (dict) Dictionary containing claim info as below, @@ -1492,16 +1516,17 @@ class Daemon(AuthJSONRPCServer): @AuthJSONRPCServer.auth_required @defer.inlineCallbacks - @AuthJSONRPCServer.flags(force='-f') def jsonrpc_resolve(self, force=False, uri=None, uris=[]): """ Resolve given LBRY URIs Usage: - resolve [-f] (<uri> | --uri=<uri>) [<uris>...] + resolve [--force] (<uri> | --uri=<uri>) [<uris>...] Options: - -f : force refresh and ignore cache + --force : (bool) force refresh and ignore cache + --uri=<uri> : (str) uri to resolve + --uris=<uris> : (list) uris to resolve Returns: Dictionary of results, keyed by uri @@ -1591,8 +1616,9 @@ class Daemon(AuthJSONRPCServer): Options: - <file_name> : specified name for the downloaded file - <timeout> : download timeout in number of seconds + --uri=<uri> : (str) uri of the content to download + --file_name=<file_name> : (str) specified name for the downloaded file + --timeout=<timeout> : (int) download timeout in number of seconds Returns: (dict) Dictionary containing information about the stream @@ -1675,15 +1701,16 @@ class Daemon(AuthJSONRPCServer): Start or stop downloading a file Usage: - file_set_status <status> [--sd_hash=<sd_hash>] [--file_name=<file_name>] - [--stream_hash=<stream_hash>] [--rowid=<rowid>] + file_set_status (<status> | --status=<status>) [--sd_hash=<sd_hash>] + [--file_name=<file_name>] [--stream_hash=<stream_hash>] [--rowid=<rowid>] Options: - --sd_hash=<sd_hash> : set status of file with matching sd hash - --file_name=<file_name> : set status of file with matching file name in the + --status=<status> : (str) one of "start" or "stop" + --sd_hash=<sd_hash> : (str) set status of file with matching sd hash + --file_name=<file_name> : (str) set status of file with matching file name in the downloads folder - --stream_hash=<stream_hash> : set status of file with matching stream hash - --rowid=<rowid> : set status of file with matching row id + --stream_hash=<stream_hash> : (str) set status of file with matching stream hash + --rowid=<rowid> : (int) set status of file with matching row id Returns: (str) Confirmation message @@ -1710,33 +1737,32 @@ class Daemon(AuthJSONRPCServer): @AuthJSONRPCServer.auth_required @defer.inlineCallbacks - @AuthJSONRPCServer.flags(delete_from_download_dir='-f', delete_all='--delete_all') def jsonrpc_file_delete(self, delete_from_download_dir=False, delete_all=False, **kwargs): """ Delete a LBRY file Usage: - file_delete [-f] [--delete_all] [--sd_hash=<sd_hash>] [--file_name=<file_name>] + file_delete [--delete_from_download_dir] [--delete_all] [--sd_hash=<sd_hash>] [--file_name=<file_name>] [--stream_hash=<stream_hash>] [--rowid=<rowid>] [--claim_id=<claim_id>] [--txid=<txid>] [--nout=<nout>] [--claim_name=<claim_name>] [--channel_claim_id=<channel_claim_id>] [--channel_name=<channel_name>] Options: - -f, --delete_from_download_dir : delete file from download directory, + --delete_from_download_dir : (bool) delete file from download directory, instead of just deleting blobs - --delete_all : if there are multiple matching files, + --delete_all : (bool) if there are multiple matching files, allow the deletion of multiple files. Otherwise do not delete anything. - --sd_hash=<sd_hash> : delete by file sd hash - --file_name<file_name> : delete by file name in downloads folder - --stream_hash=<stream_hash> : delete by file stream hash - --rowid=<rowid> : delete by file row id - --claim_id=<claim_id> : delete by file claim id - --txid=<txid> : delete by file claim txid - --nout=<nout> : delete by file claim nout - --claim_name=<claim_name> : delete by file claim name - --channel_claim_id=<channel_claim_id> : delete by file channel claim id - --channel_name=<channel_name> : delete by file channel claim name + --sd_hash=<sd_hash> : (str) delete by file sd hash + --file_name<file_name> : (str) delete by file name in downloads folder + --stream_hash=<stream_hash> : (str) delete by file stream hash + --rowid=<rowid> : (int) delete by file row id + --claim_id=<claim_id> : (str) delete by file claim id + --txid=<txid> : (str) delete by file claim txid + --nout=<nout> : (int) delete by file claim nout + --claim_name=<claim_name> : (str) delete by file claim name + --channel_claim_id=<channel_claim_id> : (str) delete by file channel claim id + --channel_name=<channel_name> : (str) delete by file channel claim name Returns: (bool) true if deletion was successful @@ -1776,10 +1802,11 @@ class Daemon(AuthJSONRPCServer): Get estimated cost for a lbry stream Usage: - stream_cost_estimate <uri> [<size> | --size=<size>] + stream_cost_estimate (<uri> | --uri=<uri>) [<size> | --size=<size>] Options: - <size>, --size=<size> : stream size in bytes. if provided an sd blob won't be + --uri=<uri> : (str) uri to use + --size=<size> : (float) stream size in bytes. if provided an sd blob won't be downloaded. Returns: @@ -1799,6 +1826,10 @@ class Daemon(AuthJSONRPCServer): channel_new (<channel_name> | --channel_name=<channel_name>) (<amount> | --amount=<amount>) + Options: + --channel_name=<channel_name> : (str) name of the channel prefixed with '@' + --amount=<amount> : (float) bid amount on the channel + Returns: (dict) Dictionary containing result of the claim { @@ -1838,6 +1869,9 @@ class Daemon(AuthJSONRPCServer): Usage: channel_list + Options: + None + Returns: (list) ClaimDict, includes 'is_mine' field to indicate if the certificate claim is in the wallet. @@ -1856,6 +1890,9 @@ class Daemon(AuthJSONRPCServer): Usage: channel_list_mine + Options: + None + Returns: (list) ClaimDict """ @@ -1871,6 +1908,9 @@ class Daemon(AuthJSONRPCServer): Usage: channel_export (<claim_id> | --claim_id=<claim_id>) + Options: + --claim_id=<claim_id> : (str) Claim ID to export information about + Returns: (str) Serialized certificate information """ @@ -1888,6 +1928,9 @@ class Daemon(AuthJSONRPCServer): channel_import (<serialized_certificate_info> | --serialized_certificate_info=<serialized_certificate_info>) + Options: + --serialized_certificate_info=<serialized_certificate_info> : (str) certificate info + Returns: (dict) Result dictionary """ @@ -1928,13 +1971,15 @@ class Daemon(AuthJSONRPCServer): [--claim_address=<claim_address>] [--change_address=<change_address>] Options: - --metadata=<metadata> : ClaimDict to associate with the claim. - --file_path=<file_path> : path to file to be associated with name. If provided, + --name=<name> : (str) name of the content + --bid=<bid> : (float) amount to back the claim + --metadata=<metadata> : (dict) ClaimDict to associate with the claim. + --file_path=<file_path> : (str) 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 sources dict is provided, it will be used. If neither are provided, an error is raised. - --fee=<fee> : Dictionary representing key fee to download content: + --fee=<fee> : (dict) Dictionary representing key fee to download content: { 'currency': currency_symbol, 'amount': float, @@ -1943,22 +1988,22 @@ class Daemon(AuthJSONRPCServer): 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 + --title=<title> : (str) title of the publication + --description=<description> : (str) description of the publication + --author=<author> : (str) author of the publication + --language=<language> : (str) language of the publication + --license=<license> : (str) publication license + --license_url=<license_url> : (str) publication license url + --thumbnail=<thumbnail> : (str) thumbnail url + --preview=<preview> : (str) preview url + --nsfw=<nsfw> : (bool) title of the publication + --sources=<sources> : (str) {'lbry_sd_hash': sd_hash} specifies sd hash of file + --channel_name=<channel_name> : (str) name of the publisher channel name in the wallet + --channel_id=<channel_id> : (str) 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 + --claim_address=<claim_address> : (str) address where the claim is sent to, if not specified new address wil automatically be created Returns: @@ -2106,7 +2151,12 @@ class Daemon(AuthJSONRPCServer): claim_abandon [<claim_id> | --claim_id=<claim_id>] [<txid> | --txid=<txid>] [<nout> | --nout=<nout>] - Return: + Options: + --claim_id=<claim_id> : (str) claim_id of the claim to abandon + --txid=<txid> : (str) txid of the claim to abandon + --nout=<nout> : (int) nout of the claim to abandon + + Returns: (dict) Dictionary containing result of the claim { txid : (str) txid of resulting transaction @@ -2134,7 +2184,12 @@ class Daemon(AuthJSONRPCServer): claim_new_support (<name> | --name=<name>) (<claim_id> | --claim_id=<claim_id>) (<amount> | --amount=<amount>) - Return: + Options: + --name=<name> : (str) name of the claim to support + --claim_id=<claim_id> : (str) claim_id of the claim to support + --amount=<amount> : (float) amount of support + + Returns: (dict) Dictionary containing result of the claim { txid : (str) txid of resulting support claim @@ -2156,7 +2211,11 @@ class Daemon(AuthJSONRPCServer): Usage: claim_renew (<outpoint> | --outpoint=<outpoint>) | (<height> | --height=<height>) - Return: + Options: + --outpoint=<outpoint> : (str) outpoint of the claim to renew + --height=<height> : (str) update claims expiring before or at this block height + + Returns: (dict) Dictionary where key is the the original claim's outpoint and value is the result of the renewal { @@ -2198,8 +2257,21 @@ class Daemon(AuthJSONRPCServer): [<amount> | --amount=<amount>] Options: - <amount> : Amount of credits to claim name for, defaults to the current amount - on the claim + --claim_id=<claim_id> : (str) claim_id to send + --address=<address> : (str) address to send the claim to + --amount<amount> : (int) Amount of credits to claim name for, defaults to the current amount + on the claim + + 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 + } + """ result = yield self.session.wallet.send_claim_to_address(claim_id, address, amount) response = yield self._render_response(result) @@ -2214,7 +2286,10 @@ class Daemon(AuthJSONRPCServer): Usage: claim_list_mine - Returns + Options: + None + + Returns: (list) List of name claims owned by user [ { @@ -2249,7 +2324,10 @@ class Daemon(AuthJSONRPCServer): Usage: claim_list (<name> | --name=<name>) - Returns + Options: + --name=<name> : (str) name of the claim to list info about + + Returns: (dict) State of claims assigned for the name { 'claims': (list) list of claims for the name @@ -2286,9 +2364,11 @@ class Daemon(AuthJSONRPCServer): [--page_size=<page_size>] Options: - --page=<page> : which page of results to return where page 1 is the first - page, defaults to no pages - --page_size=<page_size> : number of results in a page, default of 10 + --uri=<uri> : (str) uri of the channel + --uris=<uris> : (list) uris of the channel + --page=<page> : (int) which page of results to return where page 1 is the first + page, defaults to no pages + --page_size=<page_size> : (int) number of results in a page, default of 10 Returns: { @@ -2371,6 +2451,9 @@ class Daemon(AuthJSONRPCServer): Usage: transaction_list + Options: + None + Returns: (list) List of transactions @@ -2429,6 +2512,9 @@ class Daemon(AuthJSONRPCServer): Usage: transaction_show (<txid> | --txid=<txid>) + Options: + --txid=<txid> : (str) txid of the transaction + Returns: (dict) JSON formatted transaction """ @@ -2445,6 +2531,9 @@ class Daemon(AuthJSONRPCServer): Usage: wallet_is_address_mine (<address> | --address=<address>) + Options: + --address=<address> : (str) address to check + Returns: (bool) true, if address is associated with current wallet """ @@ -2461,6 +2550,9 @@ class Daemon(AuthJSONRPCServer): Usage: wallet_public_key (<address> | --address=<address>) + Options: + --address=<address> : (str) address for which to get the public key + Returns: (list) list of public keys associated with address. Could contain more than one public key if multisig. @@ -2479,6 +2571,9 @@ class Daemon(AuthJSONRPCServer): Usage: wallet_list + Options: + None + Returns: List of wallet addresses """ @@ -2495,6 +2590,9 @@ class Daemon(AuthJSONRPCServer): Usage: wallet_new_address + Options: + None + Returns: (str) New wallet address in base58 """ @@ -2517,6 +2615,9 @@ class Daemon(AuthJSONRPCServer): Usage: wallet_unused_address + Options: + None + Returns: (str) Unused wallet address in base58 """ @@ -2540,6 +2641,10 @@ class Daemon(AuthJSONRPCServer): Usage: send_amount_to_address (<amount> | --amount=<amount>) (<address> | --address=<address>) + Options: + --amount=<amount> : (float) amount to send + --address=<address> : (str) address to send credits to + Returns: (bool) true if payment successfully scheduled """ @@ -2568,7 +2673,12 @@ class Daemon(AuthJSONRPCServer): wallet_send (<amount> | --amount=<amount>) ((<address> | --address=<address>) | (<claim_id> | --claim_id=<claim_id>)) - Return: + Options: + --amount=<amount> : (float) amount of credit to send + --address=<address> : (str) address to send credits to + --claim_id=<claim_id> : (float) claim_id of the claim to send to tip to + + Returns: If sending to an address: (bool) true if payment successfully scheduled @@ -2612,6 +2722,11 @@ class Daemon(AuthJSONRPCServer): (<num_addresses> | --num_addresses=<num_addresses>) (<amount> | --amount=<amount>) + Options: + --no_broadcast : (bool) whether to broadcast or not + --num_addresses=<num_addresses> : (int) num of addresses to create + --amount=<amount> : (float) initial amount in each address + Returns: (dict) the resulting transaction """ @@ -2635,6 +2750,9 @@ class Daemon(AuthJSONRPCServer): Usage: utxo_list + Options: + None + Returns: (list) List of unspent transaction outputs (UTXOs) [ @@ -2671,8 +2789,8 @@ class Daemon(AuthJSONRPCServer): block_show (<blockhash> | --blockhash=<blockhash>) | (<height> | --height=<height>) Options: - <blockhash>, --blockhash=<blockhash> : hash of the block to look up - <height>, --height=<height> : height of the block to look up + --blockhash=<blockhash> : (str) hash of the block to look up + --height=<height> : (int) height of the block to look up Returns: (dict) Requested block @@ -2701,17 +2819,18 @@ class Daemon(AuthJSONRPCServer): [--encoding=<encoding>] [--payment_rate_manager=<payment_rate_manager>] Options: - --timeout=<timeout> : timeout in number of seconds - --encoding=<encoding> : by default no attempt at decoding is made, - can be set to one of the + --blob_hash=<blob_hash> : (str) blob hash of the blob to get + --timeout=<timeout> : (int) timeout in number of seconds + --encoding=<encoding> : (str) by default no attempt at decoding + is made, can be set to one of the following decoders: 'json' - --payment_rate_manager=<payment_rate_manager> : if not given the default payment rate + --payment_rate_manager=<payment_rate_manager> : (str) if not given the default payment rate manager will be used. supported alternative rate managers: 'only-free' - Returns + Returns: (str) Success/Fail message or (dict) decoded data """ @@ -2742,6 +2861,9 @@ class Daemon(AuthJSONRPCServer): Usage: blob_delete (<blob_hash> | --blob_hash=<blob_hash) + Options: + --blob_hash=<blob_hash> : (str) blob hash of the blob to delete + Returns: (str) Success/fail message """ @@ -2766,7 +2888,8 @@ class Daemon(AuthJSONRPCServer): peer_list (<blob_hash> | --blob_hash=<blob_hash>) [<timeout> | --timeout=<timeout>] Options: - <timeout>, --timeout=<timeout> : peer search timeout in seconds + --blob_hash=<blob_hash> : (str) find available peers for this blob hash + --timeout=<timeout> : (int) peer search timeout in seconds Returns: (list) List of contacts @@ -2780,24 +2903,23 @@ class Daemon(AuthJSONRPCServer): return d @defer.inlineCallbacks - @AuthJSONRPCServer.flags(announce_all="-a") def jsonrpc_blob_announce(self, announce_all=None, blob_hash=None, stream_hash=None, sd_hash=None): """ Announce blobs to the DHT Usage: - blob_announce [-a] [<blob_hash> | --blob_hash=<blob_hash>] + blob_announce [--announce_all] [<blob_hash> | --blob_hash=<blob_hash>] [<stream_hash> | --stream_hash=<stream_hash>] [<sd_hash> | --sd_hash=<sd_hash>] Options: - -a : announce all the blobs possessed by user - <blob_hash>, --blob_hash=<blob_hash> : announce a blob, specified by blob_hash - <stream_hash>, --stream_hash=<stream_hash> : announce all blobs associated with - stream_hash - <sd_hash>, --sd_hash=<sd_hash> : announce all blobs associated with - sd_hash and the sd_hash itself + --announce_all=<announce_all> : (bool) announce all the blobs possessed by user + --blob_hash=<blob_hash> : (str) announce a blob, specified by blob_hash + --stream_hash=<stream_hash> : (str) announce all blobs associated with + stream_hash + --sd_hash=<sd_hash> : (str) announce all blobs associated with + sd_hash and the sd_hash itself Returns: (bool) true if successful @@ -2830,6 +2952,9 @@ class Daemon(AuthJSONRPCServer): Usage: blob_announce_all + Options: + None + Returns: (str) Success/fail message """ @@ -2846,12 +2971,12 @@ class Daemon(AuthJSONRPCServer): [--reflector=<reflector>] Options: - --sd_hash=<sd_hash> : get file with matching sd hash - --file_name=<file_name> : get file with matching file name in the + --sd_hash=<sd_hash> : (str) get file with matching sd hash + --file_name=<file_name> : (str) get file with matching file name in the downloads folder - --stream_hash=<stream_hash> : get file with matching stream hash - --rowid=<rowid> : get file with matching row id - --reflector=<reflector> : reflector server, ip address or url + --stream_hash=<stream_hash> : (str) get file with matching stream hash + --rowid=<rowid> : (int) get file with matching row id + --reflector=<reflector> : (str) reflector server, ip address or url by default choose a server from the config Returns: @@ -2871,25 +2996,26 @@ class Daemon(AuthJSONRPCServer): defer.returnValue(results) @defer.inlineCallbacks - @AuthJSONRPCServer.flags(needed="-n", finished="-f") def jsonrpc_blob_list(self, uri=None, stream_hash=None, sd_hash=None, needed=None, finished=None, page_size=None, page=None): """ Returns blob hashes. If not given filters, returns all blobs known by the blob manager Usage: - blob_list [-n] [-f] [<uri> | --uri=<uri>] [<stream_hash> | --stream_hash=<stream_hash>] - [<sd_hash> | --sd_hash=<sd_hash>] [<page_size> | --page_size=<page_size>] + blob_list [--needed] [--finished] [<uri> | --uri=<uri>] + [<stream_hash> | --stream_hash=<stream_hash>] + [<sd_hash> | --sd_hash=<sd_hash>] + [<page_size> | --page_size=<page_size>] [<page> | --page=<page>] Options: - -n : only return needed blobs - -f : only return finished blobs - <uri>, --uri=<uri> : filter blobs by stream in a uri - <stream_hash>, --stream_hash=<stream_hash> : filter blobs by stream hash - <sd_hash>, --sd_hash=<sd_hash> : filter blobs by sd hash - <page_size>, --page_size=<page_size> : results page size - <page>, --page=<page> : page of results to return + --needed : (bool) only return needed blobs + --finished : (bool) only return finished blobs + --uri=<uri> : (str) filter blobs by stream in a uri + --stream_hash=<stream_hash> : (str) filter blobs by stream hash + --sd_hash=<sd_hash> : (str) filter blobs by sd hash + --page_size=<page_size> : (int) results page size + --page=<page> : (int) page of results to return Returns: (list) List of blob hashes @@ -2935,6 +3061,9 @@ class Daemon(AuthJSONRPCServer): Usage: blob_reflect_all + Options: + None + Returns: (bool) true if successful """ @@ -2951,6 +3080,9 @@ class Daemon(AuthJSONRPCServer): Usage: routing_table_get + Options: + None + Returns: (dict) dictionary containing routing and contact information { @@ -3028,8 +3160,10 @@ class Daemon(AuthJSONRPCServer): [<blob_timeout> | --blob_timeout=<blob_timeout>] Options: - <search_timeout> : how long to search for peers for the blob in the dht - <blob_timeout> : how long to try downloading from a peer + --blob_hash=<blob_hash> : (str) check availability for this blob hash + --search_timeout=<search_timeout> : (int) how long to search for peers for the blob + in the dht + --blob_timeout=<blob_timeout> : (int) how long to try downloading from a peer Returns: (dict) { @@ -3051,8 +3185,9 @@ class Daemon(AuthJSONRPCServer): [<peer_timeout> | --peer_timeout=<peer_timeout>] Options: - <sd_timeout>, --sd_timeout=<sd_timeout> : sd blob download timeout - <peer_timeout>, --peer_timeout=<peer_timeout> : how long to look for peers + --uri=<uri> : (str) check availability for this uri + --sd_timeout=<sd_timeout> : (int) sd blob download timeout + --peer_timeout=<peer_timeout> : (int) how long to look for peers Returns: (float) Peers per blob / total blobs @@ -3066,12 +3201,15 @@ class Daemon(AuthJSONRPCServer): Get stream availability for lbry uri Usage: - stream_availability (<uri>) [<search_timeout> | --search_timeout=<search_timeout>] + stream_availability (<uri> | --uri=<uri>) + [<search_timeout> | --search_timeout=<search_timeout>] [<blob_timeout> | --blob_timeout=<blob_timeout>] Options: - <search_timeout> : how long to search for peers for the blob in the dht - <blob_timeout> : how long to try downloading from a peer + --uri=<uri> : (str) check availability for this uri + --search_timeout=<search_timeout> : (int) how long to search for peers for the blob + in the dht + --search_timeout=<blob_timeout> : (int) how long to try downloading from a peer Returns: (dict) { @@ -3160,21 +3298,22 @@ class Daemon(AuthJSONRPCServer): defer.returnValue(response) @defer.inlineCallbacks - @AuthJSONRPCServer.flags(a_arg='-a', b_arg='-b') def jsonrpc_cli_test_command(self, pos_arg, pos_args=[], pos_arg2=None, pos_arg3=None, a_arg=False, b_arg=False): """ This command is only for testing the CLI argument parsing Usage: - cli_test_command [-a] [-b] (<pos_arg> | --pos_arg=<pos_arg>) + cli_test_command [--a_arg] [--b_arg] (<pos_arg> | --pos_arg=<pos_arg>) [<pos_args>...] [--pos_arg2=<pos_arg2>] [--pos_arg3=<pos_arg3>] Options: - -a, --a_arg : a arg - -b, --b_arg : b arg - <pos_arg2>, --pos_arg2=<pos_arg2> : pos arg 2 - <pos_arg3>, --pos_arg3=<pos_arg3> : pos arg 3 + --a_arg : a arg + --b_arg : b arg + --pos_arg=<pos_arg> : pos arg + --pos_args=<pos_args> : pos args + --pos_arg2=<pos_arg2> : pos arg 2 + --pos_arg3=<pos_arg3> : pos arg 3 Returns: pos args """ diff --git a/mkdocs.yml b/mkdocs.yml index 6a700297c..1455aa742 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,7 +3,7 @@ repo_url: https://github.com/lbryio/lbry pages: - "API": index.md - "CLI": cli.md -theme: material +theme: material site_dir: docs_build google_analytics: - 'UA-60403362-1' diff --git a/scripts/gen_api_docs.py b/scripts/gen_api_docs.py index b13cbf6e0..0363f35ca 100644 --- a/scripts/gen_api_docs.py +++ b/scripts/gen_api_docs.py @@ -5,63 +5,99 @@ # Push docs: mkdocs gh-deploy import inspect -import os.path as op -import re import sys - +import re +import os.path as op +from tabulate import tabulate from lbrynet.daemon.Daemon import Daemon - -def _name(obj): - if hasattr(obj, '__name__'): - return obj.__name__ - elif inspect.isdatadescriptor(obj): - return obj.fget.__name__ +INDENT = " " +REQD_CMD_REGEX = r"\(.*?=<(?P<reqd>.*?)>\)" +OPT_CMD_REGEX = r"\[.*?=<(?P<opt>.*?)>\]" +CMD_REGEX = r"--.*?(?P<cmd>.*?)[=,\s,<]" -def _anchor(name): - anchor = name.lower().replace(' ', '-') - anchor = re.sub(r'[^\w\- ]', '', anchor) - return anchor +def _tabulate_options(_options_docstr, method, reqd_matches, opt_matches): + _option_list = [] + for line in _options_docstr.splitlines(): + if (line.strip().startswith("--")): + # separates command name and description + parts = line.split(":", 1) + # checks whether the command is optional or required + # and remove the cli type formatting and convert to + # api style formatitng + match = re.findall(CMD_REGEX, parts[0]) -_docstring_header_pattern = re.compile(r'^([^\n]+)\n[\-\=]{3,}$', flags=re.MULTILINE) -_docstring_parameters_pattern = re.compile(r'^([^ \n]+) \: ([^\n]+)$', flags=re.MULTILINE) + if match[0] not in reqd_matches: + parts[0] = "'" + match[0] + "' (optional)" + else: + parts[0] = "'" + match[0] + "'" + # separates command type(in brackets) and description + new_parts = parts[1].lstrip().split(" ", 1) + else: + parts = [line] -def _replace_docstring_header(paragraph): - """Process NumPy-like function docstrings.""" + # len will be 2 when there's cmd name and description + if len(parts) == 2: + _option_list.append([parts[0], ":", new_parts[0], new_parts[1]]) + # len will be 1 when there's continuation of multiline description in the next line + # check `blob_announce`'s `stream_hash` command + elif len(parts) == 1: + _option_list.append([None, None, None, parts[0]]) + else: + print "Error: Ill formatted doc string for {}".format(method) + print "Error causing line: {}".format(line) - # Replace Markdown headers in docstrings with light headers in bold. - paragraph = re.sub(_docstring_header_pattern, r'*\1*', paragraph) - paragraph = re.sub(_docstring_parameters_pattern, r'\n* `\1` (\2)\n', paragraph) - return paragraph + # tabulate to make the options look pretty + _options_docstr_no_indent = tabulate(_option_list, missingval="", tablefmt="plain") + + # tabulate to make the options look pretty + _options_docstr = "" + for line in _options_docstr_no_indent.splitlines(): + _options_docstr += INDENT + line + '\n' + + return _options_docstr def _doc(obj): docstr = (inspect.getdoc(obj) or '').strip() - return _replace_docstring_header(docstr) + try: + _desc, _docstr_after_desc = docstr.split("Usage:", 1) + _usage_docstr, _docstr_after_options = _docstr_after_desc.split("Options:", 1) + _options_docstr, _returns_docstr = _docstr_after_options.split("Returns:", 1) + except(ValueError): + print "Error: Ill formatted doc string for {}".format(obj) + return "Error!" -def _link(name, anchor=None): - return "[{name}](#{anchor})".format(name=name, anchor=anchor or _anchor(name)) + opt_matches = re.findall(OPT_CMD_REGEX, _usage_docstr) + reqd_matches = re.findall(REQD_CMD_REGEX, _usage_docstr) + + _options_docstr = _tabulate_options(_options_docstr.strip(), obj, reqd_matches, opt_matches) + + docstr = _desc + \ + "Args:\n" + \ + _options_docstr + \ + "\nReturns:" + \ + _returns_docstr + + return docstr def main(): curdir = op.dirname(op.realpath(__file__)) - cli_doc_path = op.realpath(op.join(curdir, '..', 'docs', 'cli.md')) + api_doc_path = op.realpath(op.join(curdir, '..', 'docs', 'index.md')) - # toc = '' - doc = '' - # Table of contents + docs = '' 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" + _doc(method) + "\n```\n\n" + docs += '## ' + method_name + "\n\n```text\n" + _doc(method) + "\n```\n\n" - text = "# LBRY Command Line Documentation\n\n" + doc - with open(cli_doc_path, 'w+') as f: - f.write(text) + docs = "# LBRY JSON-RPC API Documentation\n\n" + docs + with open(api_doc_path, 'w+') as f: + f.write(docs) if __name__ == '__main__': diff --git a/scripts/gen_cli_docs.py b/scripts/gen_cli_docs.py new file mode 100644 index 000000000..f6d34bcbc --- /dev/null +++ b/scripts/gen_cli_docs.py @@ -0,0 +1,85 @@ +# -*- coding: utf-8 -*- + +# Generate docs: python gen_api_docs.py +# See docs: pip install mkdocs; mkdocs serve +# Push docs: mkdocs gh-deploy + +import inspect +import os.path as op +import sys +from tabulate import tabulate +from lbrynet.daemon.Daemon import Daemon + +INDENT = " " + + +def _tabulate_options(_options_docstr, method): + _option_list = [] + for line in _options_docstr.splitlines(): + if (line.strip().startswith("--")): + # separates command name and description + parts = line.split(":", 1) + # separates command type(in brackets) and description + new_parts = parts[1].lstrip().split(" ", 1) + else: + parts = [line] + + # len will be 2 when there's cmd name and description + if len(parts) == 2: + _option_list.append([parts[0], ":", new_parts[0], new_parts[1]]) + # len will be 1 when there's continuation of multiline description in the next line + # check `blob_announce`'s `stream_hash` command + elif len(parts) == 1: + _option_list.append([None, None, None, parts[0]]) + else: + print "Error: Ill formatted doc string for {}".format(method) + print "Error causing line: {}".format(line) + + # tabulate to make the options look pretty + _options_docstr_no_indent = tabulate(_option_list, missingval="", tablefmt="plain") + + # Indent the options properly + _options_docstr = "" + for line in _options_docstr_no_indent.splitlines(): + _options_docstr += INDENT + line + '\n' + + return _options_docstr + + +def _doc(obj): + docstr = (inspect.getdoc(obj) or '').strip() + + try: + _usage_docstr, _docstr_after_options = docstr.split("Options:", 1) + _options_docstr, _returns_docstr = _docstr_after_options.split("Returns:", 1) + except(ValueError): + print "Error: Ill formatted doc string for {}".format(obj) + return "Error!" + + _options_docstr = _tabulate_options(_options_docstr.strip(), obj) + + docstr = _usage_docstr + \ + "\nOptions:\n" + \ + _options_docstr + \ + "\nReturns:" + \ + _returns_docstr + + return docstr + + +def main(): + curdir = op.dirname(op.realpath(__file__)) + cli_doc_path = op.realpath(op.join(curdir, '..', 'docs', 'cli.md')) + + docs = '' + for method_name in sorted(Daemon.callable_methods.keys()): + method = Daemon.callable_methods[method_name] + docs += '## ' + method_name + "\n\n```text\n" + _doc(method) + "\n```\n\n" + + docs = "# LBRY Command Line Documentation\n\n" + docs + with open(cli_doc_path, 'w+') as f: + f.write(docs) + + +if __name__ == '__main__': + sys.exit(main())