From da4a24d79f58f69ebb780a0364a4ce2370a2cd22 Mon Sep 17 00:00:00 2001 From: hackrush Date: Sat, 24 Feb 2018 23:43:29 +0530 Subject: [PATCH] Added scripts to autogenerate docs and api from docstring Summary of changes Removed single dashed(short args) arguments(possibly breaking changes for app side) Standardised the docstrings Added scripts to autogenerate API and CLI documentation using the docstrings --- CHANGELOG.md | 45 ++ docs/cli.md | 750 ++++++++++++++++++++++--------- docs/index.md | 950 +++++++++++++++++++++++++++++---------- lbrynet/daemon/Daemon.py | 447 +++++++++++------- mkdocs.yml | 2 +- scripts/gen_api_docs.py | 102 +++-- scripts/gen_cli_docs.py | 85 ++++ 7 files changed, 1727 insertions(+), 654 deletions(-) create mode 100644 scripts/gen_cli_docs.py 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())