Madiator2011/lbry-sdk
1
0
Fork 0
forked from LBRYCommunity/lbry-sdk
Code Pull requests Activity

Added scripts to autogenerate docs and api from docstring

Browse source 
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
This commit is contained in:
hackrush 2018-02-24 23:43:29 +05:30
parent 95e12a208d
commit da4a24d79f
7 changed files with 1727 additions and 654 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
CHANGELOG.md
View file

@ -14,6 +14,22 @@ at anytime.
### Fixed ### 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 ### Deprecated
@ -23,6 +39,24 @@ at anytime.
### Changed ### 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 ### Added
* *
@ -105,6 +139,17 @@ at anytime.
* old storage classes used by the file manager, wallet, and blob manager * old storage classes used by the file manager, wallet, and blob manager
* old `.db` database files from the data directory * 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 ## [0.18.0] - 2017-11-08
### Fixed ### Fixed

654
docs/cli.md
View file

File diff suppressed because it is too large Load diff

872
docs/index.md
View file

File diff suppressed because it is too large Load diff

433
lbrynet/daemon/Daemon.py
View file

@ -997,17 +997,16 @@ class Daemon(AuthJSONRPCServer):
############################################################################ ############################################################################
@defer.inlineCallbacks @defer.inlineCallbacks
@AuthJSONRPCServer.flags(session_status="-s", dht_status="-d")
def jsonrpc_status(self, session_status=False, dht_status=False): def jsonrpc_status(self, session_status=False, dht_status=False):
""" """
Get daemon status Get daemon status
Usage: Usage:
status [-s] [-d] status [--session_status] [--dht_status]
Options: Options:
-s : include session status in results --session_status : (bool) include session status in results
-d : include dht network and peer status --dht_status : (bool) include dht network and peer status
Returns: Returns:
(dict) lbrynet-daemon status (dict) lbrynet-daemon status
@ -1107,6 +1106,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
version version
Options:
None
Returns: Returns:
(dict) Dictionary of lbry version information (dict) Dictionary of lbry version information
{ {
@ -1135,6 +1137,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
report_bug (<message> | --message=<message>) report_bug (<message> | --message=<message>)
Options:
--message=<message> : (str) Description of the bug
Returns: Returns:
(bool) true if successful (bool) true if successful
""" """
@ -1155,6 +1160,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
settings_get settings_get
Options:
None
Returns: Returns:
(dict) Dictionary of daemon settings (dict) Dictionary of daemon settings
See ADJUSTABLE_SETTINGS in lbrynet/conf.py for full list of 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>] [--auto_renew_claim_height_delta=<auto_renew_claim_height_delta>]
Options: Options:
--download_directory=<download_directory> : (str) --download_directory=<download_directory> : (str) path of download directory
--data_rate=<data_rate> : (float), 0.0001 --data_rate=<data_rate> : (float) 0.0001
--download_timeout=<download_timeout> : (int), 180 --download_timeout=<download_timeout> : (int) 180
--peer_port=<peer_port> : (int), 3333 --peer_port=<peer_port> : (int) 3333
--max_key_fee=<max_key_fee> : (dict) maximum key fee for downloads, --max_key_fee=<max_key_fee> : (dict) maximum key fee for downloads,
in the format: { in the format:
"currency": <currency_symbol>, {
"amount": <amount> 'currency': <currency_symbol>,
}. In the CLI, it must be an escaped 'amount': <amount>
JSON string }.
Supported currency symbols: In the CLI, it must be an escaped JSON string
LBC Supported currency symbols: LBC, USD, BTC
BTC --disable_max_key_fee=<disable_max_key_fee> : (bool) False
USD --use_upnp=<use_upnp> : (bool) True
--disable_max_key_fee=<disable_max_key_fee> : (bool), False --run_reflector_server=<run_reflector_server> : (bool) False
--use_upnp=<use_upnp> : (bool), True --cache_time=<cache_time> : (int) 150
--run_reflector_server=<run_reflector_server> : (bool), False --reflect_uploads=<reflect_uploads> : (bool) True
--cache_time=<cache_time> : (int), 150 --share_usage_data=<share_usage_data> : (bool) True
--reflect_uploads=<reflect_uploads> : (bool), True --peer_search_timeout=<peer_search_timeout> : (int) 3
--share_usage_data=<share_usage_data> : (bool), True --sd_download_timeout=<sd_download_timeout> : (int) 3
--peer_search_timeout=<peer_search_timeout> : (int), 3 --auto_renew_claim_height_delta=<auto_renew_claim_height_delta> : (int) 0
--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 claims set to expire within this many blocks will be
automatically renewed after startup (if set to 0, renews automatically renewed after startup (if set to 0, renews
will not be made automatically) will not be made automatically)
@ -1227,7 +1233,10 @@ class Daemon(AuthJSONRPCServer):
help [<command> | --command=<command>] help [<command> | --command=<command>]
Options: 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: if command is None:
@ -1256,22 +1265,25 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
commands commands
Options:
None
Returns: Returns:
(list) list of available commands (list) list of available commands
""" """
return self._render_response(sorted([command for command in self.callable_methods.keys()])) 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): def jsonrpc_wallet_balance(self, address=None, include_unconfirmed=False):
""" """
Return the balance of the wallet Return the balance of the wallet
Usage: Usage:
wallet_balance [<address> | --address=<address>] [-u] wallet_balance [<address> | --address=<address>] [--include_unconfirmed]
Options: Options:
<address> : If provided only the balance for this address will be given --address=<address> : (str) If provided only the balance for this
-u : Include unconfirmed address will be given
--include_unconfirmed : (bool) Include unconfirmed
Returns: Returns:
(float) amount of lbry credits in wallet (float) amount of lbry credits in wallet
@ -1288,7 +1300,10 @@ class Daemon(AuthJSONRPCServer):
Unlock an encrypted wallet Unlock an encrypted wallet
Usage: Usage:
wallet_unlock (<password>) wallet_unlock (<password> | --password=<password>)
Options:
--password=<password> : (str) password for unlocking wallet
Returns: Returns:
(bool) true if wallet is unlocked, otherwise false (bool) true if wallet is unlocked, otherwise false
@ -1312,6 +1327,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
wallet_decrypt wallet_decrypt
Options:
None
Returns: Returns:
(bool) true if wallet is decrypted, otherwise false (bool) true if wallet is decrypted, otherwise false
""" """
@ -1327,7 +1345,10 @@ class Daemon(AuthJSONRPCServer):
the password the password
Usage: 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: Returns:
(bool) true if wallet is decrypted, otherwise false (bool) true if wallet is decrypted, otherwise false
@ -1345,6 +1366,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
daemon_stop daemon_stop
Options:
None
Returns: Returns:
(string) Shutdown message (string) Shutdown message
""" """
@ -1355,7 +1379,6 @@ class Daemon(AuthJSONRPCServer):
defer.returnValue(response) defer.returnValue(response)
@defer.inlineCallbacks @defer.inlineCallbacks
@AuthJSONRPCServer.flags(full_status='-f')
def jsonrpc_file_list(self, **kwargs): def jsonrpc_file_list(self, **kwargs):
""" """
List files limited by optional filters 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>] 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>] [--rowid=<rowid>] [--claim_id=<claim_id>] [--outpoint=<outpoint>] [--txid=<txid>] [--nout=<nout>]
[--channel_claim_id=<channel_claim_id>] [--channel_name=<channel_name>] [--channel_claim_id=<channel_claim_id>] [--channel_name=<channel_name>]
[--claim_name=<claim_name>] [-f] [--claim_name=<claim_name>] [--full_status]
Options: Options:
--sd_hash=<sd_hash> : get file with matching sd hash --sd_hash=<sd_hash> : (str) get file with matching sd hash
--file_name=<file_name> : get file with matching file name in the --file_name=<file_name> : (str) get file with matching file name in the
downloads folder downloads folder
--stream_hash=<stream_hash> : get file with matching stream hash --stream_hash=<stream_hash> : (str) get file with matching stream hash
--rowid=<rowid> : get file with matching row id --rowid=<rowid> : (int) get file with matching row id
--claim_id=<claim_id> : get file with matching claim id --claim_id=<claim_id> : (str) get file with matching claim id
--outpoint=<outpoint> : get file with matching claim outpoint --outpoint=<outpoint> : (str) get file with matching claim outpoint
--txid=<txid> : get file with matching claim txid --txid=<txid> : (str) get file with matching claim txid
--nout=<nout> : get file with matching claim nout --nout=<nout> : (int) get file with matching claim nout
--channel_claim_id=<channel_claim_id> : get file with matching channel claim id --channel_claim_id=<channel_claim_id> : (str) get file with matching channel claim id
--channel_name=<channel_name> : get file with matching channel name --channel_name=<channel_name> : (str) get file with matching channel name
--claim_name=<claim_name> : get file with matching claim name --claim_name=<claim_name> : (str) get file with matching claim name
-f : full status, populate the 'message' and 'size' fields --full_status : (bool) full status, populate the
'message' and 'size' fields
Returns: Returns:
(list) List of files (list) List of files
@ -1420,16 +1444,16 @@ class Daemon(AuthJSONRPCServer):
defer.returnValue(response) defer.returnValue(response)
@defer.inlineCallbacks @defer.inlineCallbacks
@AuthJSONRPCServer.flags(force='-f')
def jsonrpc_resolve_name(self, name, force=False): def jsonrpc_resolve_name(self, name, force=False):
""" """
Resolve stream info from a LBRY name Resolve stream info from a LBRY name
Usage: Usage:
resolve_name <name> [-f] resolve_name (<name> | --name=<name>) [--force]
Options: 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: Returns:
(dict) Metadata dictionary from name claim, None if the name is not (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>] [<claim_id> | --claim_id=<claim_id>]
Options: Options:
<txid>, --txid=<txid> : look for claim with this txid, nout must --txid=<txid> : (str) look for claim with this txid, nout must
also be specified also be specified
<nout>, --nout=<nout> : look for claim with this nout, txid must --nout=<nout> : (int) look for claim with this nout, txid must
also be specified also be specified
<claim_id>, --claim_id=<claim_id> : look for claim with this claim id --claim_id=<claim_id> : (str) look for claim with this claim id
Returns: Returns:
(dict) Dictionary containing claim info as below, (dict) Dictionary containing claim info as below,
@ -1492,16 +1516,17 @@ class Daemon(AuthJSONRPCServer):
@AuthJSONRPCServer.auth_required @AuthJSONRPCServer.auth_required
@defer.inlineCallbacks @defer.inlineCallbacks
@AuthJSONRPCServer.flags(force='-f')
def jsonrpc_resolve(self, force=False, uri=None, uris=[]): def jsonrpc_resolve(self, force=False, uri=None, uris=[]):
""" """
Resolve given LBRY URIs Resolve given LBRY URIs
Usage: Usage:
resolve [-f] (<uri> | --uri=<uri>) [<uris>...] resolve [--force] (<uri> | --uri=<uri>) [<uris>...]
Options: 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: Returns:
Dictionary of results, keyed by uri Dictionary of results, keyed by uri
@ -1591,8 +1616,9 @@ class Daemon(AuthJSONRPCServer):
Options: Options:
<file_name> : specified name for the downloaded file --uri=<uri> : (str) uri of the content to download
<timeout> : download timeout in number of seconds --file_name=<file_name> : (str) specified name for the downloaded file
--timeout=<timeout> : (int) download timeout in number of seconds
Returns: Returns:
(dict) Dictionary containing information about the stream (dict) Dictionary containing information about the stream
@ -1675,15 +1701,16 @@ class Daemon(AuthJSONRPCServer):
Start or stop downloading a file Start or stop downloading a file
Usage: Usage:
file_set_status <status> [--sd_hash=<sd_hash>] [--file_name=<file_name>] file_set_status (<status> | --status=<status>) [--sd_hash=<sd_hash>]
[--stream_hash=<stream_hash>] [--rowid=<rowid>] [--file_name=<file_name>] [--stream_hash=<stream_hash>] [--rowid=<rowid>]
Options: Options:
--sd_hash=<sd_hash> : set status of file with matching sd hash --status=<status> : (str) one of "start" or "stop"
--file_name=<file_name> : set status of file with matching file name in the --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 downloads folder
--stream_hash=<stream_hash> : set status of file with matching stream hash --stream_hash=<stream_hash> : (str) set status of file with matching stream hash
--rowid=<rowid> : set status of file with matching row id --rowid=<rowid> : (int) set status of file with matching row id
Returns: Returns:
(str) Confirmation message (str) Confirmation message
@ -1710,33 +1737,32 @@ class Daemon(AuthJSONRPCServer):
@AuthJSONRPCServer.auth_required @AuthJSONRPCServer.auth_required
@defer.inlineCallbacks @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): def jsonrpc_file_delete(self, delete_from_download_dir=False, delete_all=False, **kwargs):
""" """
Delete a LBRY file Delete a LBRY file
Usage: 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>] [--stream_hash=<stream_hash>] [--rowid=<rowid>] [--claim_id=<claim_id>] [--txid=<txid>]
[--nout=<nout>] [--claim_name=<claim_name>] [--channel_claim_id=<channel_claim_id>] [--nout=<nout>] [--claim_name=<claim_name>] [--channel_claim_id=<channel_claim_id>]
[--channel_name=<channel_name>] [--channel_name=<channel_name>]
Options: 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 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. allow the deletion of multiple files.
Otherwise do not delete anything. Otherwise do not delete anything.
--sd_hash=<sd_hash> : delete by file sd hash --sd_hash=<sd_hash> : (str) delete by file sd hash
--file_name<file_name> : delete by file name in downloads folder --file_name<file_name> : (str) delete by file name in downloads folder
--stream_hash=<stream_hash> : delete by file stream hash --stream_hash=<stream_hash> : (str) delete by file stream hash
--rowid=<rowid> : delete by file row id --rowid=<rowid> : (int) delete by file row id
--claim_id=<claim_id> : delete by file claim id --claim_id=<claim_id> : (str) delete by file claim id
--txid=<txid> : delete by file claim txid --txid=<txid> : (str) delete by file claim txid
--nout=<nout> : delete by file claim nout --nout=<nout> : (int) delete by file claim nout
--claim_name=<claim_name> : delete by file claim name --claim_name=<claim_name> : (str) delete by file claim name
--channel_claim_id=<channel_claim_id> : delete by file channel claim id --channel_claim_id=<channel_claim_id> : (str) delete by file channel claim id
--channel_name=<channel_name> : delete by file channel claim name --channel_name=<channel_name> : (str) delete by file channel claim name
Returns: Returns:
(bool) true if deletion was successful (bool) true if deletion was successful
@ -1776,10 +1802,11 @@ class Daemon(AuthJSONRPCServer):
Get estimated cost for a lbry stream Get estimated cost for a lbry stream
Usage: Usage:
stream_cost_estimate <uri> [<size> | --size=<size>] stream_cost_estimate (<uri> | --uri=<uri>) [<size> | --size=<size>]
Options: 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. downloaded.
Returns: Returns:
@ -1799,6 +1826,10 @@ class Daemon(AuthJSONRPCServer):
channel_new (<channel_name> | --channel_name=<channel_name>) channel_new (<channel_name> | --channel_name=<channel_name>)
(<amount> | --amount=<amount>) (<amount> | --amount=<amount>)
Options:
--channel_name=<channel_name> : (str) name of the channel prefixed with '@'
--amount=<amount> : (float) bid amount on the channel
Returns: Returns:
(dict) Dictionary containing result of the claim (dict) Dictionary containing result of the claim
{ {
@ -1838,6 +1869,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
channel_list channel_list
Options:
None
Returns: Returns:
(list) ClaimDict, includes 'is_mine' field to indicate if the certificate claim (list) ClaimDict, includes 'is_mine' field to indicate if the certificate claim
is in the wallet. is in the wallet.
@ -1856,6 +1890,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
channel_list_mine channel_list_mine
Options:
None
Returns: Returns:
(list) ClaimDict (list) ClaimDict
""" """
@ -1871,6 +1908,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
channel_export (<claim_id> | --claim_id=<claim_id>) channel_export (<claim_id> | --claim_id=<claim_id>)
Options:
--claim_id=<claim_id> : (str) Claim ID to export information about
Returns: Returns:
(str) Serialized certificate information (str) Serialized certificate information
""" """
@ -1888,6 +1928,9 @@ class Daemon(AuthJSONRPCServer):
channel_import (<serialized_certificate_info> | channel_import (<serialized_certificate_info> |
--serialized_certificate_info=<serialized_certificate_info>) --serialized_certificate_info=<serialized_certificate_info>)
Options:
--serialized_certificate_info=<serialized_certificate_info> : (str) certificate info
Returns: Returns:
(dict) Result dictionary (dict) Result dictionary
""" """
@ -1928,13 +1971,15 @@ class Daemon(AuthJSONRPCServer):
[--claim_address=<claim_address>] [--change_address=<change_address>] [--claim_address=<claim_address>] [--change_address=<change_address>]
Options: Options:
--metadata=<metadata> : ClaimDict to associate with the claim. --name=<name> : (str) name of the content
--file_path=<file_path> : path to file to be associated with name. If provided, --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'. a lbry stream of this file will be used in 'sources'.
If no path is given but a sources dict is provided, If no path is given but a sources dict is provided,
it will be used. If neither are provided, an it will be used. If neither are provided, an
error is raised. 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, 'currency': currency_symbol,
'amount': float, 'amount': float,
@ -1943,22 +1988,22 @@ class Daemon(AuthJSONRPCServer):
supported currencies: LBC, USD, BTC supported currencies: LBC, USD, BTC
If an address is not provided a new one will be If an address is not provided a new one will be
automatically generated. Default fee is zero. automatically generated. Default fee is zero.
--title=<title> : title of the publication --title=<title> : (str) title of the publication
--description=<description> : description of the publication --description=<description> : (str) description of the publication
--author=<author> : author of the publication --author=<author> : (str) author of the publication
--language=<language> : language of the publication --language=<language> : (str) language of the publication
--license=<license> : publication license --license=<license> : (str) publication license
--license_url=<license_url> : publication license url --license_url=<license_url> : (str) publication license url
--thumbnail=<thumbnail> : thumbnail url --thumbnail=<thumbnail> : (str) thumbnail url
--preview=<preview> : preview url --preview=<preview> : (str) preview url
--nsfw=<nsfw> : title of the publication --nsfw=<nsfw> : (bool) title of the publication
--sources=<sources> : {'lbry_sd_hash':sd_hash} specifies sd hash of file --sources=<sources> : (str) {'lbry_sd_hash': sd_hash} specifies sd hash of file
--channel_name=<channel_name> : name of the publisher channel name in the wallet --channel_name=<channel_name> : (str) name of the publisher channel name in the wallet
--channel_id=<channel_id> : claim id of the publisher channel, does not check --channel_id=<channel_id> : (str) claim id of the publisher channel, does not check
for channel claim being in the wallet. This allows for channel claim being in the wallet. This allows
publishing to a channel where only the certificate publishing to a channel where only the certificate
private key is in the wallet. 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 new address wil automatically be created
Returns: Returns:
@ -2106,7 +2151,12 @@ class Daemon(AuthJSONRPCServer):
claim_abandon [<claim_id> | --claim_id=<claim_id>] claim_abandon [<claim_id> | --claim_id=<claim_id>]
[<txid> | --txid=<txid>] [<nout> | --nout=<nout>] [<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 (dict) Dictionary containing result of the claim
{ {
txid : (str) txid of resulting transaction 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>) claim_new_support (<name> | --name=<name>) (<claim_id> | --claim_id=<claim_id>)
(<amount> | --amount=<amount>) (<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 (dict) Dictionary containing result of the claim
{ {
txid : (str) txid of resulting support claim txid : (str) txid of resulting support claim
@ -2156,7 +2211,11 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
claim_renew (<outpoint> | --outpoint=<outpoint>) | (<height> | --height=<height>) 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 (dict) Dictionary where key is the the original claim's outpoint and
value is the result of the renewal value is the result of the renewal
{ {
@ -2198,8 +2257,21 @@ class Daemon(AuthJSONRPCServer):
[<amount> | --amount=<amount>] [<amount> | --amount=<amount>]
Options: Options:
<amount> : Amount of credits to claim name for, defaults to the current amount --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 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) result = yield self.session.wallet.send_claim_to_address(claim_id, address, amount)
response = yield self._render_response(result) response = yield self._render_response(result)
@ -2214,7 +2286,10 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
claim_list_mine claim_list_mine
Returns Options:
None
Returns:
(list) List of name claims owned by user (list) List of name claims owned by user
[ [
{ {
@ -2249,7 +2324,10 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
claim_list (<name> | --name=<name>) 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 (dict) State of claims assigned for the name
{ {
'claims': (list) list of claims for the name 'claims': (list) list of claims for the name
@ -2286,9 +2364,11 @@ class Daemon(AuthJSONRPCServer):
[--page_size=<page_size>] [--page_size=<page_size>]
Options: Options:
--page=<page> : which page of results to return where page 1 is the first --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, defaults to no pages
--page_size=<page_size> : number of results in a page, default of 10 --page_size=<page_size> : (int) number of results in a page, default of 10
Returns: Returns:
{ {
@ -2371,6 +2451,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
transaction_list transaction_list
Options:
None
Returns: Returns:
(list) List of transactions (list) List of transactions
@ -2429,6 +2512,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
transaction_show (<txid> | --txid=<txid>) transaction_show (<txid> | --txid=<txid>)
Options:
--txid=<txid> : (str) txid of the transaction
Returns: Returns:
(dict) JSON formatted transaction (dict) JSON formatted transaction
""" """
@ -2445,6 +2531,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
wallet_is_address_mine (<address> | --address=<address>) wallet_is_address_mine (<address> | --address=<address>)
Options:
--address=<address> : (str) address to check
Returns: Returns:
(bool) true, if address is associated with current wallet (bool) true, if address is associated with current wallet
""" """
@ -2461,6 +2550,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
wallet_public_key (<address> | --address=<address>) wallet_public_key (<address> | --address=<address>)
Options:
--address=<address> : (str) address for which to get the public key
Returns: Returns:
(list) list of public keys associated with address. (list) list of public keys associated with address.
Could contain more than one public key if multisig. Could contain more than one public key if multisig.
@ -2479,6 +2571,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
wallet_list wallet_list
Options:
None
Returns: Returns:
List of wallet addresses List of wallet addresses
""" """
@ -2495,6 +2590,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
wallet_new_address wallet_new_address
Options:
None
Returns: Returns:
(str) New wallet address in base58 (str) New wallet address in base58
""" """
@ -2517,6 +2615,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
wallet_unused_address wallet_unused_address
Options:
None
Returns: Returns:
(str) Unused wallet address in base58 (str) Unused wallet address in base58
""" """
@ -2540,6 +2641,10 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
send_amount_to_address (<amount> | --amount=<amount>) (<address> | --address=<address>) 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: Returns:
(bool) true if payment successfully scheduled (bool) true if payment successfully scheduled
""" """
@ -2568,7 +2673,12 @@ class Daemon(AuthJSONRPCServer):
wallet_send (<amount> | --amount=<amount>) wallet_send (<amount> | --amount=<amount>)
((<address> | --address=<address>) | (<claim_id> | --claim_id=<claim_id>)) ((<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: If sending to an address:
(bool) true if payment successfully scheduled (bool) true if payment successfully scheduled
@ -2612,6 +2722,11 @@ class Daemon(AuthJSONRPCServer):
(<num_addresses> | --num_addresses=<num_addresses>) (<num_addresses> | --num_addresses=<num_addresses>)
(<amount> | --amount=<amount>) (<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: Returns:
(dict) the resulting transaction (dict) the resulting transaction
""" """
@ -2635,6 +2750,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
utxo_list utxo_list
Options:
None
Returns: Returns:
(list) List of unspent transaction outputs (UTXOs) (list) List of unspent transaction outputs (UTXOs)
[ [
@ -2671,8 +2789,8 @@ class Daemon(AuthJSONRPCServer):
block_show (<blockhash> | --blockhash=<blockhash>) | (<height> | --height=<height>) block_show (<blockhash> | --blockhash=<blockhash>) | (<height> | --height=<height>)
Options: Options:
<blockhash>, --blockhash=<blockhash> : hash of the block to look up --blockhash=<blockhash> : (str) hash of the block to look up
<height>, --height=<height> : height of the block to look up --height=<height> : (int) height of the block to look up
Returns: Returns:
(dict) Requested block (dict) Requested block
@ -2701,17 +2819,18 @@ class Daemon(AuthJSONRPCServer):
[--encoding=<encoding>] [--payment_rate_manager=<payment_rate_manager>] [--encoding=<encoding>] [--payment_rate_manager=<payment_rate_manager>]
Options: Options:
--timeout=<timeout> : timeout in number of seconds --blob_hash=<blob_hash> : (str) blob hash of the blob to get
--encoding=<encoding> : by default no attempt at decoding is made, --timeout=<timeout> : (int) timeout in number of seconds
can be set to one of the --encoding=<encoding> : (str) by default no attempt at decoding
is made, can be set to one of the
following decoders: following decoders:
'json' '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. manager will be used.
supported alternative rate managers: supported alternative rate managers:
'only-free' 'only-free'
Returns Returns:
(str) Success/Fail message or (dict) decoded data (str) Success/Fail message or (dict) decoded data
""" """
@ -2742,6 +2861,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
blob_delete (<blob_hash> | --blob_hash=<blob_hash) blob_delete (<blob_hash> | --blob_hash=<blob_hash)
Options:
--blob_hash=<blob_hash> : (str) blob hash of the blob to delete
Returns: Returns:
(str) Success/fail message (str) Success/fail message
""" """
@ -2766,7 +2888,8 @@ class Daemon(AuthJSONRPCServer):
peer_list (<blob_hash> | --blob_hash=<blob_hash>) [<timeout> | --timeout=<timeout>] peer_list (<blob_hash> | --blob_hash=<blob_hash>) [<timeout> | --timeout=<timeout>]
Options: 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: Returns:
(list) List of contacts (list) List of contacts
@ -2780,23 +2903,22 @@ class Daemon(AuthJSONRPCServer):
return d return d
@defer.inlineCallbacks @defer.inlineCallbacks
@AuthJSONRPCServer.flags(announce_all="-a")
def jsonrpc_blob_announce(self, announce_all=None, blob_hash=None, def jsonrpc_blob_announce(self, announce_all=None, blob_hash=None,
stream_hash=None, sd_hash=None): stream_hash=None, sd_hash=None):
""" """
Announce blobs to the DHT Announce blobs to the DHT
Usage: 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>] [<stream_hash> | --stream_hash=<stream_hash>]
[<sd_hash> | --sd_hash=<sd_hash>] [<sd_hash> | --sd_hash=<sd_hash>]
Options: Options:
-a : announce all the blobs possessed by user --announce_all=<announce_all> : (bool) announce all the blobs possessed by user
<blob_hash>, --blob_hash=<blob_hash> : announce a blob, specified by blob_hash --blob_hash=<blob_hash> : (str) announce a blob, specified by blob_hash
<stream_hash>, --stream_hash=<stream_hash> : announce all blobs associated with --stream_hash=<stream_hash> : (str) announce all blobs associated with
stream_hash stream_hash
<sd_hash>, --sd_hash=<sd_hash> : announce all blobs associated with --sd_hash=<sd_hash> : (str) announce all blobs associated with
sd_hash and the sd_hash itself sd_hash and the sd_hash itself
Returns: Returns:
@ -2830,6 +2952,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
blob_announce_all blob_announce_all
Options:
None
Returns: Returns:
(str) Success/fail message (str) Success/fail message
""" """
@ -2846,12 +2971,12 @@ class Daemon(AuthJSONRPCServer):
[--reflector=<reflector>] [--reflector=<reflector>]
Options: Options:
--sd_hash=<sd_hash> : get file with matching sd hash --sd_hash=<sd_hash> : (str) get file with matching sd hash
--file_name=<file_name> : get file with matching file name in the --file_name=<file_name> : (str) get file with matching file name in the
downloads folder downloads folder
--stream_hash=<stream_hash> : get file with matching stream hash --stream_hash=<stream_hash> : (str) get file with matching stream hash
--rowid=<rowid> : get file with matching row id --rowid=<rowid> : (int) get file with matching row id
--reflector=<reflector> : reflector server, ip address or url --reflector=<reflector> : (str) reflector server, ip address or url
by default choose a server from the config by default choose a server from the config
Returns: Returns:
@ -2871,25 +2996,26 @@ class Daemon(AuthJSONRPCServer):
defer.returnValue(results) defer.returnValue(results)
@defer.inlineCallbacks @defer.inlineCallbacks
@AuthJSONRPCServer.flags(needed="-n", finished="-f")
def jsonrpc_blob_list(self, uri=None, stream_hash=None, sd_hash=None, needed=None, def jsonrpc_blob_list(self, uri=None, stream_hash=None, sd_hash=None, needed=None,
finished=None, page_size=None, page=None): finished=None, page_size=None, page=None):
""" """
Returns blob hashes. If not given filters, returns all blobs known by the blob manager Returns blob hashes. If not given filters, returns all blobs known by the blob manager
Usage: Usage:
blob_list [-n] [-f] [<uri> | --uri=<uri>] [<stream_hash> | --stream_hash=<stream_hash>] blob_list [--needed] [--finished] [<uri> | --uri=<uri>]
[<sd_hash> | --sd_hash=<sd_hash>] [<page_size> | --page_size=<page_size>] [<stream_hash> | --stream_hash=<stream_hash>]
[<sd_hash> | --sd_hash=<sd_hash>]
[<page_size> | --page_size=<page_size>]
[<page> | --page=<page>] [<page> | --page=<page>]
Options: Options:
-n : only return needed blobs --needed : (bool) only return needed blobs
-f : only return finished blobs --finished : (bool) only return finished blobs
<uri>, --uri=<uri> : filter blobs by stream in a uri --uri=<uri> : (str) filter blobs by stream in a uri
<stream_hash>, --stream_hash=<stream_hash> : filter blobs by stream hash --stream_hash=<stream_hash> : (str) filter blobs by stream hash
<sd_hash>, --sd_hash=<sd_hash> : filter blobs by sd hash --sd_hash=<sd_hash> : (str) filter blobs by sd hash
<page_size>, --page_size=<page_size> : results page size --page_size=<page_size> : (int) results page size
<page>, --page=<page> : page of results to return --page=<page> : (int) page of results to return
Returns: Returns:
(list) List of blob hashes (list) List of blob hashes
@ -2935,6 +3061,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
blob_reflect_all blob_reflect_all
Options:
None
Returns: Returns:
(bool) true if successful (bool) true if successful
""" """
@ -2951,6 +3080,9 @@ class Daemon(AuthJSONRPCServer):
Usage: Usage:
routing_table_get routing_table_get
Options:
None
Returns: Returns:
(dict) dictionary containing routing and contact information (dict) dictionary containing routing and contact information
{ {
@ -3028,8 +3160,10 @@ class Daemon(AuthJSONRPCServer):
[<blob_timeout> | --blob_timeout=<blob_timeout>] [<blob_timeout> | --blob_timeout=<blob_timeout>]
Options: Options:
<search_timeout> : how long to search for peers for the blob in the dht --blob_hash=<blob_hash> : (str) check availability for this blob hash
<blob_timeout> : how long to try downloading from a peer --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: Returns:
(dict) { (dict) {
@ -3051,8 +3185,9 @@ class Daemon(AuthJSONRPCServer):
[<peer_timeout> | --peer_timeout=<peer_timeout>] [<peer_timeout> | --peer_timeout=<peer_timeout>]
Options: Options:
<sd_timeout>, --sd_timeout=<sd_timeout> : sd blob download timeout --uri=<uri> : (str) check availability for this uri
<peer_timeout>, --peer_timeout=<peer_timeout> : how long to look for peers --sd_timeout=<sd_timeout> : (int) sd blob download timeout
--peer_timeout=<peer_timeout> : (int) how long to look for peers
Returns: Returns:
(float) Peers per blob / total blobs (float) Peers per blob / total blobs
@ -3066,12 +3201,15 @@ class Daemon(AuthJSONRPCServer):
Get stream availability for lbry uri Get stream availability for lbry uri
Usage: 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>] [<blob_timeout> | --blob_timeout=<blob_timeout>]
Options: Options:
<search_timeout> : how long to search for peers for the blob in the dht --uri=<uri> : (str) check availability for this uri
<blob_timeout> : how long to try downloading from a peer --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: Returns:
(dict) { (dict) {
@ -3160,21 +3298,22 @@ class Daemon(AuthJSONRPCServer):
defer.returnValue(response) defer.returnValue(response)
@defer.inlineCallbacks @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, def jsonrpc_cli_test_command(self, pos_arg, pos_args=[], pos_arg2=None, pos_arg3=None,
a_arg=False, b_arg=False): a_arg=False, b_arg=False):
""" """
This command is only for testing the CLI argument parsing This command is only for testing the CLI argument parsing
Usage: 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_args>...] [--pos_arg2=<pos_arg2>]
[--pos_arg3=<pos_arg3>] [--pos_arg3=<pos_arg3>]
Options: Options:
-a, --a_arg : a arg --a_arg : a arg
-b, --b_arg : b arg --b_arg : b arg
<pos_arg2>, --pos_arg2=<pos_arg2> : pos arg 2 --pos_arg=<pos_arg> : pos arg
<pos_arg3>, --pos_arg3=<pos_arg3> : pos arg 3 --pos_args=<pos_args> : pos args
--pos_arg2=<pos_arg2> : pos arg 2
--pos_arg3=<pos_arg3> : pos arg 3
Returns: Returns:
pos args pos args
""" """

102
scripts/gen_api_docs.py
View file

@ -5,63 +5,99 @@
# Push docs: mkdocs gh-deploy # Push docs: mkdocs gh-deploy
import inspect import inspect
import os.path as op
import re
import sys import sys
import re
import os.path as op
from tabulate import tabulate
from lbrynet.daemon.Daemon import Daemon from lbrynet.daemon.Daemon import Daemon
INDENT = " "
def _name(obj): REQD_CMD_REGEX = r"\(.*?=<(?P<reqd>.*?)>\)"
if hasattr(obj, '__name__'): OPT_CMD_REGEX = r"\[.*?=<(?P<opt>.*?)>\]"
return obj.__name__ CMD_REGEX = r"--.*?(?P<cmd>.*?)[=,\s,<]"
elif inspect.isdatadescriptor(obj):
return obj.fget.__name__
def _anchor(name): def _tabulate_options(_options_docstr, method, reqd_matches, opt_matches):
anchor = name.lower().replace(' ', '-') _option_list = []
anchor = re.sub(r'[^\w\- ]', '', anchor) for line in _options_docstr.splitlines():
return anchor 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) if match[0] not in reqd_matches:
_docstring_parameters_pattern = re.compile(r'^([^ \n]+) \: ([^\n]+)$', flags=re.MULTILINE) 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): # len will be 2 when there's cmd name and description
"""Process NumPy-like function docstrings.""" 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. # tabulate to make the options look pretty
paragraph = re.sub(_docstring_header_pattern, r'*\1*', paragraph) _options_docstr_no_indent = tabulate(_option_list, missingval="", tablefmt="plain")
paragraph = re.sub(_docstring_parameters_pattern, r'\n* `\1` (\2)\n', paragraph)
return paragraph # 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): def _doc(obj):
docstr = (inspect.getdoc(obj) or '').strip() 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): opt_matches = re.findall(OPT_CMD_REGEX, _usage_docstr)
return "[{name}](#{anchor})".format(name=name, anchor=anchor or _anchor(name)) 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(): def main():
curdir = op.dirname(op.realpath(__file__)) 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 = '' docs = ''
doc = ''
# Table of contents
for method_name in sorted(Daemon.callable_methods.keys()): for method_name in sorted(Daemon.callable_methods.keys()):
method = Daemon.callable_methods[method_name] method = Daemon.callable_methods[method_name]
# toc += '* ' + _link(method_name, _anchor(method_name)) + "\n" docs += '## ' + method_name + "\n\n```text\n" + _doc(method) + "\n```\n\n"
doc += '## ' + method_name + "\n\n```text\n" + _doc(method) + "\n```\n\n"
text = "# LBRY Command Line Documentation\n\n" + doc docs = "# LBRY JSON-RPC API Documentation\n\n" + docs
with open(cli_doc_path, 'w+') as f: with open(api_doc_path, 'w+') as f:
f.write(text) f.write(docs)
if __name__ == '__main__': if __name__ == '__main__':

85
scripts/gen_cli_docs.py Normal file
View file

@ -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())