From d06211015d41a812b3729eaa6b5032349642eabc Mon Sep 17 00:00:00 2001 From: Alex Grintsvayg Date: Thu, 8 Dec 2016 22:05:31 -0500 Subject: [PATCH] api doc generator --- .gitignore | 1 + docs/api.md | 528 +++++++++++++++++++++++++++++++ docs/index.md | 3 + lbrynet/lbrynet_daemon/Daemon.py | 8 +- mkdocs.yml | 7 + scripts/gen_api_docs.py | 109 +++++++ 6 files changed, 649 insertions(+), 7 deletions(-) create mode 100644 docs/api.md create mode 100644 docs/index.md create mode 100644 mkdocs.yml create mode 100644 scripts/gen_api_docs.py diff --git a/.gitignore b/.gitignore index 4cce3d364..9395abc8e 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ /build /dist /lbrynet.egg-info +/docs_build .idea/.name .coverage diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 000000000..ef41fa41f --- /dev/null +++ b/docs/api.md @@ -0,0 +1,528 @@ +# LBRY JSON-RPC API Documentation + +## abandon_name + +```text +DEPRECIATED, use abandon_claim + +Args: + 'txid': txid of claim, string +Return: + txid +``` + +## blob_announce_all + +```text +Announce all blobs to the DHT + +Args: + None +Returns: +``` + +## blob_get + +```text +Download and return a sd blob + +Args: + sd_hash +Returns + sd blob, dict +``` + +## blob_list + +```text +Returns all blob hashes + +Args: + None +Returns: + list of blob hashes +``` + +## blob_reflect_all + +```text +Reflects all saved blobs + +Args: + None +Returns: + True +``` + +## block_show + +```text +Get contents of a block + +Args: + blockhash: hash of the block to look up +Returns: + requested block +``` + +## claim_abandon + +```text +Abandon a name and reclaim credits from the claim + +Args: + 'txid': txid of claim, string + 'nout': nout of claim, integer +Return: + txid : txid of resulting transaction if succesful + fee : fee paid for the transaction if succesful +``` + +## claim_list + +```text +Get claims for a name + +Args: + name: file name + txid: transaction id of a name claim transaction +Returns + list of name claims +``` + +## claim_list_mine + +```text +List my name claims + +Args: + None +Returns + list of name claims +``` + +## claim_new_support + +```text +Support a name claim + +Args: + 'name': name + 'claim_id': claim id of claim to support + 'amount': amount to support by +Return: + txid : txid of resulting transaction if succesful + nout : nout of the resulting support claim if succesful + fee : fee paid for the transaction if succesful +``` + +## claim_show + +```text +Resolve claim info from a LBRY uri + +Args: + 'name': name to look up, string, do not include lbry:// prefix + 'txid': optional, if specified, look for claim with this txid + 'nout': optional, if specified, look for claim with this nout + +Returns: + txid, amount, value, n, height +``` + +## commands + +```text +Return a list of available commands + +Returns: + list +``` + +## configure_ui + +```text +Configure the UI being hosted + +Args, optional: + 'branch': a branch name on lbryio/lbry-web-ui + 'path': path to a ui folder +``` + +## daemon_stop + +```text +Stop lbrynet-daemon + +Returns: + shutdown message +``` + +## file_delete + +```text +Delete a lbry file + +Args: + 'file_name': downloaded file name, string +Returns: + confirmation message +``` + +## file_get + +```text +Get a file + +Args: + 'name': get file by lbry uri, + 'sd_hash': get file by the hash in the name claim, + 'file_name': get file by its name in the downloads folder, +Returns: + 'completed': bool + 'file_name': string + 'key': hex string + 'points_paid': float + 'stopped': bool + 'stream_hash': base 58 string + 'stream_name': string + 'suggested_file_name': string + 'upload_allowed': bool + 'sd_hash': string +``` + +## file_list + +```text +List files + +Args: + None +Returns: + List of files, with the following keys: + 'completed': bool + 'file_name': string + 'key': hex string + 'points_paid': float + 'stopped': bool + 'stream_hash': base 58 string + 'stream_name': string + 'suggested_file_name': string + 'upload_allowed': bool + 'sd_hash': string +``` + +## file_seed + +```text +Start or stop seeding a file + +Args: + 'status': "start" or "stop" + 'name': start file by lbry uri, + 'sd_hash': start file by the hash in the name claim, + 'file_name': start file by its name in the downloads folder, +Returns: + confirmation message +``` + +## get + +```text +Download stream from a LBRY uri. + +Args: + 'name': name to download, string + 'download_directory': optional, path to directory where file will be saved, string + 'file_name': optional, a user specified name for the downloaded file + 'stream_info': optional, specified stream info overrides name + 'timeout': optional + 'wait_for_write': optional, defaults to True. When set, waits for the file to + only start to be written before returning any results. +Returns: + 'stream_hash': hex string + 'path': path of download +``` + +## get_availability + +```text +Get stream availability for a winning claim + +Arg: + name (str): lbry uri + +Returns: + peers per blob / total blobs +``` + +## get_mean_availability + +```text +Get mean blob availability + +Args: + None +Returns: + Mean peers for a blob +``` + +## get_nametrie + +```text +Get the nametrie + +Args: + None +Returns: + Name claim trie +``` + +## help + +```text +Return a useful message for an API command + +Args: + 'command': optional, command to retrieve documentation for +Returns: + if given a command, returns documentation about that command + otherwise returns general help message +``` + +## peer_list + +```text +Get peers for blob hash + +Args: + 'blob_hash': blob hash +Returns: + List of contacts +``` + +## publish + +```text +Make a new name claim and publish associated data to lbrynet + +Args: + 'name': name to be claimed, string + 'file_path': path to file to be associated with name, string + 'bid': amount of credits to commit in this claim, float + 'metadata': metadata dictionary + optional 'fee' +Returns: + 'success' : True if claim was succesful , False otherwise + 'reason' : if not succesful, give reason + 'txid' : txid of resulting transaction if succesful + 'nout' : nout of the resulting support claim if succesful + 'fee' : fee paid for the claim transaction if succesful + 'claimid' : claimid of the resulting transaction +``` + +## reflect + +```text +Reflect a stream + +Args: + sd_hash: sd_hash of lbry file +Returns: + True or traceback +``` + +## report_bug + +```text +Report a bug to slack + +Args: + 'message': string, message to send +Returns: + True if successful +``` + +## resolve_name + +```text +Resolve stream info from a LBRY uri + +Args: + 'name': name to look up, string, do not include lbry:// prefix +Returns: + metadata from name claim +``` + +## reveal + +```text +Reveal a file or directory in file browser + +Args: + 'path': path to be selected in file browser +Returns: + True, opens file browser +``` + +## send_amount_to_address + +```text +Send credits to an address + +Args: + amount: the amount to send + address: the address of the recipient +Returns: + True if payment successfully scheduled +``` + +## settings_get + +```text +Get lbrynet daemon settings + +Args: + None +Returns: + 'run_on_startup': bool, + 'data_rate': float, + 'max_key_fee': float, + 'download_directory': string, + 'max_upload': float, 0.0 for unlimited + 'max_download': float, 0.0 for unlimited + 'upload_log': bool, + 'search_timeout': float, + 'download_timeout': int + 'max_search_results': int, + 'wallet_type': string, + 'delete_blobs_on_remove': bool, + 'peer_port': int, + 'dht_node_port': int, + 'use_upnp': bool, +``` + +## settings_set + +```text +Set lbrynet daemon settings + +Args: + 'run_on_startup': bool, + 'data_rate': float, + 'max_key_fee': float, + 'download_directory': string, + 'max_upload': float, 0.0 for unlimited + 'max_download': float, 0.0 for unlimited + 'upload_log': bool, + 'download_timeout': int +Returns: + settings dict +``` + +## status + +```text +Return daemon status + +Args: + session_status: bool + blockchain_status: bool +Returns: + daemon status +``` + +## stream_cost_estimate + +```text +Get estimated cost for a lbry stream + +Args: + 'name': lbry uri + 'size': stream size, in bytes. if provided an sd blob won't be downloaded. +Returns: + estimated cost +``` + +## transaction_list + +```text +List transactions + +Args: + None +Returns: + list of transactions +``` + +## transaction_show + +```text +Get a decoded transaction from a txid + +Args: + txid: txid hex string +Returns: + JSON formatted transaction +``` + +## version + +```text +Get lbry version information + +Args: + None +Returns: + "platform": platform string + "os_release": os release string + "os_system": os name + "lbrynet_version: ": lbrynet_version, + "lbryum_version: ": lbryum_version, + "ui_version": commit hash of ui version being used + "remote_lbrynet": most recent lbrynet version available from github + "remote_lbryum": most recent lbryum version available from github +``` + +## wallet_balance + +```text +Return the balance of the wallet + +Returns: + balance, float +``` + +## wallet_is_address_mine + +```text +Checks if an address is associated with the current wallet. + +Args: + address: string +Returns: + is_mine: bool +``` + +## wallet_new_address + +```text +Generate a new wallet address + +Args: + None +Returns: + new wallet address, base 58 string +``` + +## wallet_public_key + +```text +Get public key from wallet address + +Args: + wallet: wallet address, base58 +Returns: + public key +``` + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..79a4fe16a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,3 @@ +# LBRY Documentation + +## [API Documentation](/api/) diff --git a/lbrynet/lbrynet_daemon/Daemon.py b/lbrynet/lbrynet_daemon/Daemon.py index 0aabf5046..ca32c76f9 100644 --- a/lbrynet/lbrynet_daemon/Daemon.py +++ b/lbrynet/lbrynet_daemon/Daemon.py @@ -11,7 +11,6 @@ import requests import urllib import simplejson as json import textwrap -from urllib2 import urlopen from decimal import Decimal from twisted.web import server @@ -1835,6 +1834,7 @@ class Daemon(AuthJSONRPCServer): def jsonrpc_claim_abandon(self, p): """ Abandon a name and reclaim credits from the claim + Args: 'txid': txid of claim, string 'nout': nout of claim, integer @@ -2434,12 +2434,6 @@ class Daemon(AuthJSONRPCServer): return d - @AuthJSONRPCServer.auth_required - def jsonrpc_test_api_authentication(self): - if self._use_authentication: - return self._render_response(True) - return self._render_response("Not using authentication") - def jsonrpc_get_start_notice(self): """ DEPRECATED. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..01391391f --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,7 @@ +site_name: LBRY +repo_url: https://github.com/lbryio/lbry +pages: + - Home: index.md + - "JSON-RPC API": api.md +#theme: readthedocs +site_dir: docs_build diff --git a/scripts/gen_api_docs.py b/scripts/gen_api_docs.py new file mode 100644 index 000000000..1ec0af523 --- /dev/null +++ b/scripts/gen_api_docs.py @@ -0,0 +1,109 @@ +# -*- 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 re +import sys + +from six import string_types +from lbrynet.lbrynet_daemon.Daemon import Daemon + + +def _name(obj): + if hasattr(obj, '__name__'): + return obj.__name__ + elif inspect.isdatadescriptor(obj): + return obj.fget.__name__ + + +def _anchor(name): + anchor = name.lower().replace(' ', '-') + anchor = re.sub(r'[^\w\- ]', '', anchor) + return anchor + + +_docstring_header_pattern = re.compile(r'^([^\n]+)\n[\-\=]{3,}$', flags=re.MULTILINE) +_docstring_parameters_pattern = re.compile(r'^([^ \n]+) \: ([^\n]+)$', flags=re.MULTILINE) + + +def _replace_docstring_header(paragraph): + """Process NumPy-like function docstrings.""" + + # 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 + + +def _doc(obj): + docstr = (inspect.getdoc(obj) or '').strip() + return _replace_docstring_header(docstr) if docstr and '---' in docstr else docstr + + +def _is_public(obj): + name = _name(obj) if not isinstance(obj, string_types) else obj + if name: + return not name.startswith('_') + else: + return True + + +def _is_defined_in_package(obj, package): + if isinstance(obj, property): + obj = obj.fget + mod = inspect.getmodule(obj) + if mod and hasattr(mod, '__name__'): + name = mod.__name__ + return name.split('.')[0] == package + return True + + +def _iter_doc_members(obj, package=None): + for _, member in inspect.getmembers(obj): + if _is_public(member): + if package is None or _is_defined_in_package(member, package): + yield member + + +def _iter_methods(klass, package=None): + for member in _iter_doc_members(klass, package): + if inspect.isfunction(member) or inspect.ismethod(member): + if inspect.isdatadescriptor(member): + continue + if _name(member).startswith('jsonrpc_'): + yield member + + +def _link(name, anchor=None): + return "[{name}](#{anchor})".format(name=name, anchor=anchor or _anchor(name)) + + +def main(): + curdir = op.dirname(op.realpath(__file__)) + path = op.realpath(op.join(curdir, '..', 'docs', 'api.md')) + + klass = Daemon + + # toc = '' + doc = '' + # Table of contents + for method in _iter_methods(klass): + method_name = _name(method)[len('jsonrpc_'):] + method_doc = _doc(method) + if "DEPRECATED" in method_doc: + continue + # toc += '* ' + _link(method_name, _anchor(method_name)) + "\n" + doc += '## ' + method_name + "\n\n```text\n" + method_doc + "\n```\n\n" + + text = "# LBRY JSON-RPC API Documentation\n\n" + doc + + with open(path, 'w+') as f: + f.write(text) + + +if __name__ == '__main__': + sys.exit(main())