Avro
  1. Avro
  2. AVRO-52

Need a usage/lifecycle test to explain the python API

    Details

    • Type: Test Test
    • Status: Open
    • Priority: Major Major
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: python
    • Labels:
      None

      Description

      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.

      1. AVRO-52.patch
        3 kB
        Philip Zeyliger

        Activity

        Hide
        Philip Zeyliger added a comment -

        Sure. Would be great for the quickstart(s) to be part of the project itself, though, so that they're easier to find.

        Show
        Philip Zeyliger added a comment - Sure. Would be great for the quickstart(s) to be part of the project itself, though, so that they're easier to find.
        Hide
        Jeff Hammerbacher added a comment -

        Does Patrick Hunt's Avro RPC Quickstart on Github satisfy the requirements of this ticket? http://github.com/phunt/avro-rpc-quickstart

        Show
        Jeff Hammerbacher added a comment - Does Patrick Hunt's Avro RPC Quickstart on Github satisfy the requirements of this ticket? http://github.com/phunt/avro-rpc-quickstart
        Hide
        Philip Zeyliger added a comment -

        +1 to the examples/ tree idea.

        Show
        Philip Zeyliger added a comment - +1 to the examples/ tree idea.
        Hide
        Sharad Agarwal added a comment -

        we should have an examples/ tree that contains runnable code, that we can run from unit tests. We could also link to it from the documentation.

        +1

        Show
        Sharad Agarwal added a comment - we should have an examples/ tree that contains runnable code, that we can run from unit tests. We could also link to it from the documentation. +1
        Hide
        Doug Cutting added a comment -

        What should we do with this? Perhaps we should have an examples/ tree that contains runnable code, that we can run from unit tests. We could also link to it from the documentation. Thoughts?

        Show
        Doug Cutting added a comment - What should we do with this? Perhaps we should have an examples/ tree that contains runnable code, that we can run from unit tests. We could also link to it from the documentation. Thoughts?
        Hide
        Philip Zeyliger added a comment -

        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.

        Show
        Philip Zeyliger added a comment - 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.
        Hide
        Sharad Agarwal added a comment -

        Aren't the existing tests also doing the similar thing? In case more coverage is required, we can add more tests but for API usage illustration etc, won't tutorial documentation be more helpful than tests ? I think we should add to the docs to illustrate python APIs.

        Show
        Sharad Agarwal added a comment - Aren't the existing tests also doing the similar thing? In case more coverage is required, we can add more tests but for API usage illustration etc, won't tutorial documentation be more helpful than tests ? I think we should add to the docs to illustrate python APIs.
        Hide
        Philip Zeyliger added a comment -

        Attaching a very first pass of such a test. Someone more familiar with the APIs should take a look to see if I'm using them as intended, and there are several TODOs.

        Show
        Philip Zeyliger added a comment - Attaching a very first pass of such a test. Someone more familiar with the APIs should take a look to see if I'm using them as intended, and there are several TODOs.

          People

          • Assignee:
            Jeff Hammerbacher
            Reporter:
            Philip Zeyliger
          • Votes:
            1 Vote for this issue
            Watchers:
            5 Start watching this issue

            Dates

            • Created:
              Updated:

              Development