bfa2397176
According to http://docs.python.org/2/library/unittest.html assert(Not)Equals is a deprecated alias of assert(Not)Equal. Change-Id: I0973455847410a34e1f9e5fe81ba096186f225d2 Closes-Bug: #1329757
3.9 KiB
Provide a set of examples for oslo libraries
https://blueprints.launchpad.net/oslo.messaging/+spec/oslo-examples
For each oslo library provide a set of examples to illustrate a use case of a specific library API.
Problem description
For now we have no any example (except tests) of how to use each oslo library. Functional tests are close to be, but they are more abstract and serve to check the functionality, not to illustrate the way how it can be used in the application.
It is desirable to have some expressive examples which could serve as documentation for the code.
Proposed change
In each oslo library repository create an examples folder, where put some examples for the library API.
It is preferrable that example be like a mini application, and built in terms of some application domain, not as "ClientA calls ServerB with request1".
We can implement a set of examples for oslo.messaging in the same manner as in taskflow:
https://github.com/openstack/taskflow/tree/master/taskflow/examples The examples all get tested during unit test runs to ensure they work as expected.
They are also should be part of the documentation, and be built as docs. There will be a separate file in the docs folder that includes the code in the examples folder.
https://raw.githubusercontent.com/openstack/taskflow/master/doc/source/examples.rst
An example may look like the following:
bobMessenger = messenger.Client(cfg, 'Bob')
aliceMessenger = messenger.Client(cfg, 'Alice')
server = messenger.Server(cfg)
server.run()
bobMessenger.run()
aliceMessenger.run()
time.sleep(2) # wait for all participants discover each other
assertEqual(server.clientsList,
bobMessenger.clientsList,
aliceMessenger.clientsList)
bobMessenger.sendMessage('Alice', 'Hi, there!')
assertEqual(bobMessenger.history['Alice'],
aliceMessenger.history['Bob'])Or for the request-reply pattern:
fibServer = fibonacci.Server(cfg)
fibClient = fibonacci.Client(cfg)
fibServer.run()
value = fibClient.getFibonacci(20)
assertEqual(value, 6765)Alternatives
Functional tests built on top of some real-world application which uses oslo libraries for its implementation. A kind of indirect testing which may show the way how the library could be improved or optimised. Such testing also serves as an example of usage, because we test the application which uses the library and therefore demonstrates how to use the API.
https://blueprints.launchpad.net/oslo.messaging/+spec/oslo-functional-testing-apps
Impact on Existing APIs
None
Security impact
None
Performance Impact
None
Configuration Impact
None
Developer Impact
Any future changes to oslo.* API should be reflected in the examples.
Testing Impact
All examples should run with unit tests.
Implementation
Assignee(s)
- Primary assignee:
- Other contributors:
Milestones
Target Milestone for completion: * liberty-3
Work Items
- Develop examples for each oslo library
taskflow - got as a pattern
We are going to start with oslo.messaging and oslo.concurrency and move on to the other libraries when the work is done.
Incubation
N/A
Documentation Impact
Example apps should be published in the documentation.
See how it is done in taskflow:
https://raw.githubusercontent.com/openstack/taskflow/master/doc/source/examples.rst
This gets converted into:
http://docs.openstack.org/developer/taskflow/examples.html
Dependencies
oslo.*
References
None