[ 
https://issues.apache.org/jira/browse/AVRO-52?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12719718#action_12719718
 ] 

Philip Zeyliger commented on AVRO-52:
-------------------------------------

It is true that a usage test wouldn't add much more in the way of coverage, but 
that's not its sole point.  Think of it more as a first draft of a tutorial: a 
new user could look through it and see how the APIs are intended to be used.  
Of course, this could be written as a static documentation page, but, the 
trouble with that is, for a new project live AVRO, it will get out of date very 
quickly.  Having the tutorial code enshrined in a unit test helps.  When faced 
with a new technology, I tend to go straight towards the examples, and some of 
the best examples are typically in the test code: that code shows both how to 
use it, and what it should be doing.  

I suspect it'll be nice to have some very simple tests banging around, since 
they tend to be easier to debug.  The random-data tests are thorough, but 
they're quite tricky to understand.

One way to approach this could be as python doctests 
(http://docs.python.org/library/doctest.html), but, in practice, I find the 
regular unittest framework to be easier to work with.

> Need a usage/lifecycle test to explain the python API
> -----------------------------------------------------
>
>                 Key: AVRO-52
>                 URL: https://issues.apache.org/jira/browse/AVRO-52
>             Project: Avro
>          Issue Type: Test
>          Components: python
>            Reporter: Philip Zeyliger
>         Attachments: AVRO-52.patch
>
>
> AVRO/python will eventually need something analogous to 
> http://wiki.apache.org/thrift/ThriftUsagePython, the Thrift Lightning talk at 
> http://x1024.net/blog/, or  
> http://code.google.com/apis/protocolbuffers/docs/pythontutorial.html .  While 
> the API is still being developed, however, it may make sense to simply have a 
> unit test that illustrates reasonable usage of the APIs.  This can also serve 
> as a place that users look at to learn the APIs and comment on their 
> friendliness and pythonicity.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Reply via email to