Repository: kytos/python-openflow

Issue:
Improve Introduction and first sections on sphinx documentation

Comments:

Patch:
diff --git a/README.rst b/README.rst
index 3e7eddc..4712d69 100644
--- a/README.rst
+++ b/README.rst
@@ -1,32 +1,40 @@
 |Experimental| |Openflow| |Tag| |Release| |Pypi| |Tests| |License|
 
 Overview
---------
+========
 
-*python-openflow* is a low level library to parse OpenFlow messages. If you
-want to read an OpenFlow packet from an open socket or send a message to an
-OpenFlow switch, this is your best friend. The main features are: high
+*python-openflow* is a low level library to parse and create OpenFlow messages.
+If you want to read an OpenFlow packet from an open socket or send a message to
+an OpenFlow switch, this is your best friend. The main features are: high
 performance, short learning curve and free software license.
 
-This library is part of `Kytos <http://kytos.io>`_ project. *python-openflow*
-was developed to be used with *Kytos* controller, but feel free to use this
-simple and intuitive library in other projects.
+This library is part of `Kytos <http://kytos.io>`_ project, but feel free to
+use this simple and intuitive library in other projects.
 
-This is just an overview for you to check whether this project fit your needs.
-For a more detailed documentation, please check the :doc:`python-openflow API
-Reference Manual <pyof>`.
+.. attention::
+   *python-openflow* does not perform I/O operations. To communicate with a
+   switch, you can use, for example, `Kyco <http://docs.kytos.io/kyco>`_, the
+   Kytos Controller.
+
+A quick start follows for you to check whether this project fits your needs.
+For a more detailed documentation, please check the
+`python-openflow API Reference Manual <http://docs.kytos.io/python-openflow/pyof/>`_.
+
+Quick Start
+-----------
 
 Installing
 ^^^^^^^^^^
 
 For now, you can install this package from source (if you have cloned this
-repository) or via pip.
+repository) or via pip. If you are a more experienced Python user, you can
+also install it without root permissions.
 
 .. note:: We are improving this and soon you will be able to install from the
- major distros repositories.
+ major distros' repositories.
 
 From PyPI
-=========
+"""""""""
 
 *python-openflow* is in PyPI, so you can easily install it via `pip3` (`pip`
 for Python 3) or include this project in your `requirements.txt`. To install it
@@ -37,7 +45,7 @@ with `pip3`, run the following command:
    $ sudo pip3 install python-openflow
 
 From source code
-================
+""""""""""""""""
 
 First you need to clone `python-openflow` repository:
 
@@ -56,7 +64,7 @@ install procedure:
 Basic Usage Example
 ^^^^^^^^^^^^^^^^^^^
 
-See how easy is the creation of a features request message with this library.
+See how it is easy to create a feature request message with this library.
 You can use ipython3 to get the advantages of autocompletion:
 
 .. code-block:: python
@@ -67,19 +75,33 @@ You can use ipython3 to get the advantages of autocompletion:
     Type.OFPT_FEATURES_REQUEST
 
 If you need to send this message via socket, call the ``pack()`` method to get
-its binary representation that should be used to be sent throught the network:
+its binary representation to be sent through the network:
 
-.. code:: python3
+.. code:: python
 
     >>> binary_msg = request.pack()
+    >>> print(binary_msg)
+    b"\x01\x05\x00\x08\x14\xad'\x8d"
+    >>> # Use a controller (e.g. Kytos Controller) to send "binary_msg"
 
-Please note that this library do not send or receive messages via socket. You
-have to create your own server to receive messages from switches. This library
-only helps you to handle OpenFlow messages on a more pythonic way.
+To parse a message, use ``unpack_message()``:
 
-.. seealso::
+.. code:: python
+
+   >>> from pyof.v0x01.common.utils import unpack_message
+   >>> binary_msg = b"\x01\x05\x00\x08\x14\xad'\x8d"
+   >>> msg = unpack_message(binary_msg)
+   >>> print(msg.header.message_type)
+   Type.OFPT_FEATURES_REQUEST
+
+Please, note that this library do not send or receive messages via socket. You
+have to create your own server to receive messages from switches. This library
+only helps you to handle OpenFlow messages in a more pythonic way.
+To communicate with switches, we also develop *Kyco*, the Kytos Controller.
 
-    To see more examples, please visit our :doc:`examples/index` chapter.
+.. hint::
+   To see more examples, please visit our
+   `Examples <http://docs.kytos.io/python-openflow/examples>`_ section.
 
 .. |Experimental| image:: https://img.shields.io/badge/stability-experimental-orange.svg
 .. |Openflow| image:: https://img.shields.io/badge/Openflow-1.0.0-brightgreen.svg
diff --git a/pyof/v0x01/common/header.py b/pyof/v0x01/common/header.py
index 1e62b87..c0489e5 100644
--- a/pyof/v0x01/common/header.py
+++ b/pyof/v0x01/common/header.py
@@ -73,7 +73,7 @@ class Header(GenericStruct):
     length = UBInt16()
     xid = UBInt32()
 
-    def __init__(self, message_type=None, length=None, xid=randint(0, MAXID)):
+    def __init__(self, message_type=None, length=None, xid=None):
         """The constructor takes the optional parameters below.
 
         Args:
@@ -84,4 +84,4 @@ class Header(GenericStruct):
         super().__init__()
         self.message_type = message_type
         self.length = length
-        self.xid = xid
+        self.xid = randint(0, MAXID) if xid is None else xid


Test patch:
diff --git a/tests/v0x01/test_common/test_header.py b/tests/v0x01/test_common/test_header.py
index 003621c..3c01fd8 100644
--- a/tests/v0x01/test_common/test_header.py
+++ b/tests/v0x01/test_common/test_header.py
@@ -1,6 +1,7 @@
 """Testing Header structure."""
 import os
 import unittest
+from unittest.mock import patch
 
 from pyof.v0x01.common.header import Header, Type
 
@@ -43,3 +44,9 @@ class TestHeader(unittest.TestCase):
         self.assertEqual(self.message.version, 1)
 
         f.close()
+
+    @patch('pyof.v0x01.common.header.randint')
+    def test_random_xid(self, m):
+        """Each Header instantiations without xid should call randint."""
+        Header(), Header()  # noqa
+        self.assertEqual(m.call_count, 2)