diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/development/xmlrpc.md | 61 | ||||
| -rw-r--r-- | docs/usage/xmlrpc.md | 37 |
2 files changed, 68 insertions, 30 deletions
diff --git a/docs/development/xmlrpc.md b/docs/development/xmlrpc.md index cfa5acf..141dec9 100644 --- a/docs/development/xmlrpc.md +++ b/docs/development/xmlrpc.md @@ -1,5 +1,9 @@ # The XML-RPC API +**NOTE:** This guide covers development information for the Patchwork XML-RPC +API. For general usage of the API, refer to the [usage +documentation][doc-usage]. + Patchwork provides an XML-RPC API. This API can be used to be used to retrieve and modify information about patches, projects and more. @@ -19,33 +23,30 @@ Where `patchwork.example.com` refers to the URL of your Patchwork instance. introduced in Patchwork v1.1. Prior versions of Patchwork do not offer this functionality. -## Developing Your Own Client - -You need to connect to the server. Some methods require authentication (via -HTTP Basic Auth) while others do not. Authentication uses your Patchwork -account and the on-server documentation will indicate where it is necessary. -We will only cover the unauthenticated method here for brevity - please -consult the [`xmlrpclib`] documentation for more detailed examples: - - from __future__ import print_function - import sys - import xmlrpclib - - url = 'http://patchwork.example.org/xmlrpc/' - - try: - rpc = xmlrpclib.ServerProxy(url) - except: - print('Unable to connect to %s\n' % url, file=sys.stderr) - sys.exit(1) - -After connecting, the `rpc` object will be populated with a list of available -functions (or procedures, in RPC terminology). For example, if we continue -with the above example: - - print(rpc.pw_rpc_version()) - -It should be possible to use all the methods listed in the -[server's documentation](#patchwork-api-documentation). - -[`xmlrpclib`]: https://docs.python.org/2/library/xmlrpclib.html +## Interacting with the API + +**NOTE:** The Patchwork XML-RPC API provides a number of "methods". Some +methods require authentication (via HTTP Basic Auth) while others do not. +Authentication uses your Patchwork account and the on-server documentation will +indicate where it is necessary. We will only cover the unauthenticated method +here for brevity - please consult the [`xmlrpclib`][ref-xmlrpclib] +documentation for more detailed examples: + +To interact with the Patchwork XML-RPC API, a XML-RPC library should be used. +Python provides such a library - [`xmlrpclib`][ref-xmlrpclib] - in its standard +library. For example, to get the version of the XML-RPC API for a Patchwork +instance hosted at `patchwork.example.com`, run: + + $ python + >>> import xmlrpclib # or 'xmlrpc.client' for Python 3 + >>> rpc = xmlrpclib.ServerProxy('http://patchwork.example.com/xmlrpc/') + >>> rpc.pw_rpc_version() + 1.1 + +Once connected, the `rpc` object will be populated with a list of available +functions (or procedures, in RPC terminology). In the above example, we used +the `pw_rpc_version` method, however, it should be possible to use all the +methods listed in the [server documentation](#patchwork-api-documentation). + +[doc-usage]: ../usage/xmlrpc.md +[ref-xmlrpclib]: https://docs.python.org/2/library/xmlrpclib.html diff --git a/docs/usage/xmlrpc.md b/docs/usage/xmlrpc.md new file mode 100644 index 0000000..de95a07 --- /dev/null +++ b/docs/usage/xmlrpc.md @@ -0,0 +1,37 @@ +# The XML-RPC API + +**NOTE:** This guide covers usage information for the Patchwork XML-RPC API. +For information on developing custom applications or clients for this API, +refer to the [developers documentation][doc-development]. + +Patchwork provides an XML-RPC API. This API can be used to be used to retrieve +and modify information about patches, projects and more. + +**NOTE:** The XML-RPC API can be enabled/disabled by the administrator: it may +not be available in every instance. + +## pwclient + +The `pwclient` application, provided with Patchwork, can be used to interact +with Patchwork from the command line. Functionality provided by `pwclient` +includes: + +* Listing patches, projects, and checks +* Downloading and applying patches to a local code base +* Modifying the status of patches +* Creating new checks + +pwclient can be downloaded from the [Ozlabs Patchwork instance][ref-pw-oz], or +at the following path for other Patchwork instances: + + http://patchwork.example.com/pwclient/ + +where `patchwork.example.com` corresponds to the URL a Patchwork instance is +hosted at. + +Once downloaded, to view information about all the operations supported by +`pwclient`, run: + + $ pwclient --help + +[doc-development]: ../development/xmlrpc.md |