OMGeeky/google-apis-rs
1
0
Fork 0
mirror of https://github.com/OMGeeky/google-apis-rs.git synced 2026-01-07 03:56:42 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs(todos): result handling and remaining todos

Browse Source 
Basically there is no todo left, which puts us in a good position for
implementing more features, and get some feedback in the meanwhile.
This commit is contained in:
Sebastian Thiel
2015-03-13 15:01:32 +01:00
parent 9a17ab9e4e
commit 4cf365d026
6 changed files with 265 additions and 224 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
etc/api/shared.yaml
View File

@@ -37,7 +37,8 @@ cargo:
keywords: [google, protocol, web, api]
# All APIs should live in the same repository
repository_url: https://github.com/Byron/google-apis-rs
urls:
authenticator_delegate: ../yup-oauth2/trait.AuthenticatorDelegate.html
copyright:
license_abbrev: "MIT"
# should at some point be 2015-2016 ...

51
gen/youtube3/README.md
View File

@@ -68,15 +68,16 @@ supports various methods to configure the impending operation (not shown here).
specified right away (i.e. `(...)`), whereas all optional ones can be [build up][builder-pattern] as desired.
The `doit()` method performs the actual communication with the server and returns the respective result.
# Usage (*TODO*)
# Usage
## Instantiating the Hub
## A complete example
```Rust
extern crate hyper;
extern crate "yup-oauth2" as oauth2;
extern crate "rustc-serialize" as rustc_serialize;
extern crate youtube3;
# use youtube3::cmn::Result;
use std::default::Default;
use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage};
# use youtube3::YouTube;
@@ -104,29 +105,51 @@ let result = hub.live_broadcasts().list("part")
.id("kasd")
.broadcast_status("accusam")
.doit();
// TODO: show how to handle the result !
match result {
Result::HttpError(err) => println!("HTTPERROR: {:?}", err),
Result::FieldClash(clashed_field) => println!("FIELD CLASH: {:?}", clashed_field),
Result::Success(value) => println!("Result Value: {:?}", value),
}
```
**TODO** Example calls - there should soon be a generator able to do that with proper inputs
## Handling Errors
# Some details
All errors produced by the system are provided either as [Result](cmn/enum.Result.html) enumeration as return value of
the doit() methods, or handed as possibly intermediate results to either the
[Hub Delegate](cmn/trait.Delegate.html), or the [Authenticator Delegate](../yup-oauth2/trait.AuthenticatorDelegate.html).
When delegates handle errors or intermediate values, they may have a chance to instruct the system to retry. This
makes the system potentially resilient to all kinds of errors.
## About Customization/Callbacks
## About parts
You may alter the way an `doit()` method is called by providing a [delegate](cmn/trait.Delegate.html) to the
[Method Builder](cmn/trait.MethodBuilder.html) before making the final `doit()` call.
Respective methods will be called to provide progress information, as well as determine whether the system should
retry on failure.
* Optionals needed for Json, otherwise I'd happily drop them
* explain that examples use all response parts, even though they are shown for request values
The [delegate trait](cmn/trait.Delegate.html) is default-implemented, allowing you to customize it with minimal effort.
## About builder arguments
## About Parts
* pods are copy
* strings are &str
* request values are borrowed
* additional parameters using `param()`
All structures provided by this library are made to be [enocodable](cmn/trait.RequestValue.html) and
[decodable](cmn/trait.ResponseResult.html) via json. Optionals are used to indicate that partial requests are responses are valid.
Most optionals are are considered [Parts](cmn/trait.Part.html) which are identifyable by name, which will be sent to
the server to indicate either the set parts of the request or the desired parts in the response.
## About Builder Arguments
Using [method builders](cmn/trait.MethodBuilder.html), you are able to prepare an action call by repeatedly calling it's methods.
These will always take a single argument, for which the following statements are true.
* [PODs][wiki-pod] are handed by copy
* strings are passed as `&str`
* [request values](cmn/trait.RequestValue.html) are borrowed
Arguments will always be copied or cloned into the builder, to make them independent of their original life times.
[wiki-pod]: http://en.wikipedia.org/wiki/Plain_old_data_structure
[builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern
[google-go-api]: https://github.com/google/google-api-go-client

360
gen/youtube3/src/lib.rs
View File

File diff suppressed because it is too large Load Diff

57
src/mako/lib/lib.mako
View File

@@ -2,7 +2,8 @@
rust_test_fn_invisible, rust_doc_test_norun, rust_doc_comment, markdown_rust_block,
unindent_first_by, mangle_ident, mb_type, singular, scope_url_to_variant,
PART_MARKER_TRAIT, RESOURCE_MARKER_TRAIT, METHOD_BUILDER_MARKERT_TRAIT,
find_fattest_resource, build_all_params, pass_through, parts_from_params) %>\
find_fattest_resource, build_all_params, pass_through, parts_from_params,
REQUEST_MARKER_TRAIT, RESPONSE_MARKER_TRAIT) %>\
<%namespace name="util" file="util.mako"/>\
<%namespace name="mbuild" file="mbuild.mako"/>\
@@ -15,6 +16,11 @@
# fr == fattest resource, the fatter, the more important, right ?
fr = find_fattest_resource(c)
hub_url = 'struct.' + hub_type(c.schemas, util.canonical_name()) + '.html'
method_builder_url = 'cmn/trait.' + METHOD_BUILDER_MARKERT_TRAIT + '.html'
delegate_url = 'cmn/trait.Delegate.html'
request_trait_url = 'cmn/trait.' + REQUEST_MARKER_TRAIT + '.html'
response_trait_url = 'cmn/trait.' + RESPONSE_MARKER_TRAIT + '.html'
part_trait_url = 'cmn/trait.' + PART_MARKER_TRAIT + '.html'
%>\
# Features
@@ -55,10 +61,10 @@ The API is structured into the following primary items:
* **[Resources](cmn/trait.${RESOURCE_MARKER_TRAIT}.html)**
* primary types that you can apply *Activities* to
* a collection of properties and *Parts*
* **[Parts](cmn/trait.${PART_MARKER_TRAIT}.html)**
* **[Parts](${part_trait_url})**
* a collection of properties
* never directly used in *Activities*
* **[Activities](cmn/trait.${METHOD_BUILDER_MARKERT_TRAIT}.html)**
* **[Activities](${method_builder_url})**
* operations to apply to *Resources*
Generally speaking, you can invoke *Activities* like this:
@@ -83,32 +89,49 @@ supports various methods to configure the impending operation (not shown here).
specified right away (i.e. `(...)`), whereas all optional ones can be [build up][builder-pattern] as desired.
The `${api.terms.action}()` method performs the actual communication with the server and returns the respective result.
# Usage (*TODO*)
# Usage
${'##'} Instantiating the Hub
${'##'} A complete example
${self.hub_usage_example(c, rust_doc, fr=fr)}\
**TODO** Example calls - there should soon be a generator able to do that with proper inputs
${'##'} Handling Errors
# Some details
All errors produced by the system are provided either as [Result](cmn/enum.Result.html) enumeration as return value of
the ${api.terms.action}() methods, or handed as possibly intermediate results to either the
[Hub Delegate](${delegate_url}), or the [Authenticator Delegate](${urls.authenticator_delegate}).
When delegates handle errors or intermediate values, they may have a chance to instruct the system to retry. This
makes the system potentially resilient to all kinds of errors.
${'##'} About Customization/Callbacks
${'##'} About parts
You may alter the way an `${api.terms.action}()` method is called by providing a [delegate](${delegate_url}) to the
[Method Builder](${method_builder_url}) before making the final `${api.terms.action}()` call.
Respective methods will be called to provide progress information, as well as determine whether the system should
retry on failure.
* Optionals needed for Json, otherwise I'd happily drop them
* explain that examples use all response parts, even though they are shown for request values
The [delegate trait](${delegate_url}) is default-implemented, allowing you to customize it with minimal effort.
${'##'} About builder arguments
${'##'} About Parts
* pods are copy
* strings are &str
* request values are borrowed
* additional parameters using `param()`
All structures provided by this library are made to be [enocodable](${request_trait_url}) and
[decodable](${response_trait_url}) via json. Optionals are used to indicate that partial requests are responses are valid.
Most optionals are are considered [Parts](${part_trait_url}) which are identifyable by name, which will be sent to
the server to indicate either the set parts of the request or the desired parts in the response.
${'##'} About Builder Arguments
Using [method builders](${method_builder_url}), you are able to prepare an action call by repeatedly calling it's methods.
These will always take a single argument, for which the following statements are true.
* [PODs][wiki-pod] are handed by copy
* strings are passed as `&str`
* [request values](${request_trait_url}) are borrowed
Arguments will always be copied or cloned into the builder, to make them independent of their original life times.
[wiki-pod]: http://en.wikipedia.org/wiki/Plain_old_data_structure
[builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern
[google-go-api]: https://github.com/google/google-api-go-client
</%def>
@@ -169,7 +192,7 @@ let mut hub = ${hub_type}::new(hyper::Client::new(), auth);\
# end fill in values
%>\
% if fr:
${mbuild.usage(resource, method, m, params, request_value, parts, show_all=True, rust_doc=rust_doc)}\
${mbuild.usage(resource, method, m, params, request_value, parts, show_all=True, rust_doc=rust_doc, handle_result=True)}\
% else:
<%block filter="main_filter">\
${util.test_prelude()}\

16
src/mako/lib/mbuild.mako
View File

@@ -39,7 +39,7 @@
ThisType = mb_type(resource, method) + mb_tparams
params, request_value = build_all_params(c, m)
part_prop, parts = parts_from_params(params)
part_desc = make_parts_desc(part_prop)
parts = get_parts(part_prop)
@@ -209,7 +209,7 @@ ${self._setter_fn(resource, method, m, p, part_prop, ThisType, c)}\
## documented example for a given method.
###############################################################################################
###############################################################################################
<%def name="usage(resource, method, m, params, request_value, parts=None, show_all=False, rust_doc=True)">\
<%def name="usage(resource, method, m, params, request_value, parts=None, show_all=False, rust_doc=True, handle_result=False)">\
<%
hub_type_name = hub_type(schemas, util.canonical_name())
required_props, optional_props, part_prop = organize_params(params, request_value)
@@ -259,6 +259,9 @@ ${capture(util.test_prelude) | hide_filter}\
% if request_value:
# use ${util.library_name()}::${request_value.id};
% endif
% if handle_result:
# use ${util.library_name()}::cmn::Result;
% endif
% if media_params:
# use std::fs;
% endif
@@ -306,7 +309,14 @@ let result = hub.${mangle_ident(resource)}().${mangle_ident(method)}(${required_
% endfor
${'.' + action_name | indent_by(13)}(${action_args});
// TODO: show how to handle the result !
% if handle_result:
match result {
Result::HttpError(err) => println!("HTTPERROR: {:?}", err),
Result::FieldClash(clashed_field) => println!("FIELD CLASH: {:?}", clashed_field),
Result::Success(value) => println!("Result Value: {:?}", value),
}
% endif
</%block>
</%block>\
</%def>

2
src/mako/lib/schema.mako
View File

@@ -31,7 +31,7 @@ ${struct};
<%def name="new(s, c)">\
<%
markers = schema_markers(s, c)
traits = ['Default', 'Clone']
traits = ['Default', 'Clone', 'Debug']
if REQUEST_MARKER_TRAIT in markers:
traits.append('RustcEncodable')