x/python-redfish
Code Issues Proposed changes

Merge pull request #66 from uggla/devel

Browse Source 
Documentation update
This commit is contained in:
Bruno Cornec 2016-04-07 15:37:29 +02:00
commit 88873ba107
10 changed files with 90 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CONTRIBUTING.rst
View File

@ -2,4 +2,4 @@ If you would like to contribute to the development of this project.
Submit your pull request and issues to https://github.com/bcornec/python-redfish.
You can also share and discuss on the mailing list as well.
You can also share and discuss on the mailing list as well at http://mondorescue.org/sympa/arc/python-redfish.

24
README.rst
View File

@ -1,13 +1,13 @@
python-redfish
==============
The python-redfish project
==========================
This repository will be used to house the Redfish python library, a reference
This repository will be used to house the python-redfish library, a reference
implementation to enable Python developers to communicate with the Redfish API
(http://www.dmtf.org/standards/redfish).
NOTE::
DRAFT - WORK IN PROGRESS
STATUS: Work in progress, ready for proof of concept.
The current Redfish specification revision is 1.0.0 - Note that the mockup
is still at version 0.99.0a and may not reflect what the standard provides
@ -20,7 +20,7 @@ The full documentation is available at
http://pythonhosted.org/python-redfish/installation.html
Project Structure
-------------------
-----------------
This project follows the same convention as OpenStack projects, eg. using pbr
for build and test automation::
@ -34,7 +34,7 @@ for build and test automation::
pbconf # Project builder file to build rpm/deb packages for
# distributions
redfish/ # The redfish library itself
redfish/tests/ # Python redfish unit test suite
redfish/tests/ # python-redfish unit test suite
redfish-client # Client tool to manage redfish devices
Requirements
@ -49,17 +49,19 @@ are discouraged due to security.
Python requirements are listed in requirements.txt; additional requirements for
running the unit test suite are listed in test-requirements.txt.
Note: Running tests requires Docker engine.
Note: The program was tested with Python 2.7.10 and 3.4.2 however it might work
as well with all Python 3 releases.
Get the sources
---------------
Get the source code
-------------------
The sources are available on github and can be retrieved using::
The source code is available on github and can be retrieved using::
git clone https://github.com/uggla/python-redfish
git clone https://github.com/bcornec/python-redfish
As python redefish is currently in heavy development we recommend to checkout the devel branch using::
As python-redfish is currently in heavy development we recommend to checkout the devel branch using::
cd python-redfish
git checkout devel

2
doc/source/develsetup.rst
View File

@ -2,7 +2,7 @@
Developer setup
===============
#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
#. Follow `get the source code <http://pythonhosted.org/python-redfish/readme.html#get-the-source-code>`_ section to retrieve the sources.
#. Follow `using pip and virtualenv <http://pythonhosted.org/python-redfish/installation.html#using-pip-and-virtualenv>`_ section to create your environment.
You can start hacking the code now.

1
doc/source/help.rst
View File

@ -5,7 +5,6 @@ Help required
We need help on the following topic:
- debian/ubuntu dependencies packaging.
- python3 testing.
- installation on distributions which are not Fedora or Mageia.
- documentation.

112
doc/source/installation.rst
View File

@ -2,22 +2,36 @@
Installation
============
Using pip
---------
Use::
The following instructions are ordered by ease of use, and our project recommendations.
sudo pip install python-redfish
Pip will install :
Using rpm packages
------------------
1. The library and all dependencies into prefix/lib/pythonX.Y/site-packages directory
2. Redfish client master conf file into prefix/etc/redfish_client.conf
Unless if prefix = '/usr', in that case force configuration file to be in /etc
There is currently no official Linux distribution packages.
3. Data file (templates) into prefix/share/redfish-client/templates
The upstream project provides packages for a limited set of Linux distributions.
Point 2 and 3 above need root access to your system. If you don't have root
access on your system, please follow `Using pip and virtualenv`_ section.
There are available at ftp://ftp.project-builder.org
As an example for Fedora 23 use the following:
1. As root get the repo file::
cd /etc/yum.repos.d && wget ftp://ftp.project-builder.org/fedora/23/x86_64/python-redfish.repo
2. Install using dnf::
dnf install python-redfish
..
Using deb package
-----------------
This installation in not yet possible due to missing deb package dependencies. We are working on it.
In the meantime we recommend to use `Using pip`_ or `Using pip and virtualenv`_.
Using pip and virtualenv
@ -51,29 +65,47 @@ Using pip and virtualenv
All files are installed under your virtualenv.
Using the sources
Using pip
---------
Use::
sudo pip install python-redfish
Pip will install :
1. The library and all dependencies into prefix/lib/pythonX.Y/site-packages directory
2. redfish-client conf file into prefix/etc/redfish-client.conf.
If prefix = '/usr' then force the configuration file to be in /etc
3. Data files (templates) into prefix/share/redfish-client/templates
Point 2 and 3 above need root access to your system. If you don't have root
access on your system, please follow `Using pip and virtualenv`_ section.
Using source code
-----------------
#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
#. Install from the source using::
#. Follow `get the source code <http://pythonhosted.org/python-redfish/readme.html#get-the-source-code>`_ section to retrieve it.
#. Install from the source code using::
python setup.py install --prefix="/usr/local"
Using rpm package
-----------------
Building your own rpm packages
------------------------------
There is currently no oficial packages for distributions.
However part of the sources there is a mechanism to buil rpm or deb packages for distributions.
Inside the project tree there is a mechanism to build rpm packages for distributions.
The mechanism is based on `project builder <http://www.project-builder.org/>`_ tool.
#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
#. Follow `get the source code <http://pythonhosted.org/python-redfish/readme.html#get-the-source-code>`_ section to retrieve it.
#. Download project builder for your distribution from ftp://ftp.project-builder.org.
#. Clone the project to your own github account.
#. Create a .pbrc with the following content, replace "/wokspace/python/redfish" and "uggla" with your own directory and account::
#. Create a .pbrc with the following content, replace "/workspace/python/redfish" and "uggla" with your own directory and account::
[uggla@ugglalaptop ~]$ cat .pbrc
$ cat .pbrc
pbdefdir python-redfish = $ENV{'HOME'}/workspace
pbconfdir python-redfish = $ENV{'HOME'}/workspace/python-redfish/pbconf
pbconfurl python-redfish = git+ssh://git@github.com:uggla/python-redfish.git
@ -82,27 +114,17 @@ The mechanism is based on `project builder <http://www.project-builder.org/>`_ t
pb -p python-redfish sbx2pkg
or::
or::
pb -p python-redfish sbx2pkg2ins
#. All packages (srpm/rpm) should be available into the build directory, then install the package using rpm::
rpm -Uvh python-redfish/build/RPMS/python-redfish-devel20160213182552.rpm
#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
Using deb package
-----------------
This installation in not yet possible due to missing deb package dependencies. We are working on it.
In the meantime we recommend to use `Using pip`_ or `Using pip and virtualenv`_.
=====================================
Host configuration file configuration
=====================================
============================
Inventory file configuration
============================
#. Verify redfish-client is working correclty::
@ -116,12 +138,16 @@ Host configuration file configuration
redfish-client config showall
Note: The inventory file is created in $HOME/.redfish
===================
Mockup installation
===================
#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
#. Install docker using your distribution packages or the docker `procedure <https://docs.docker.com/engine/installation/>`_ (docker provide more recent packages for ubuntu)::
#. Follow `get the source code <http://pythonhosted.org/python-redfish/readme.html#get-the-source-code>`_ section to retrieve it.
#. Install docker using your distribution packages or the docker `procedure <https://docs.docker.com/engine/installation/>`_ (docker provides more recent packages):
As an example for Fedora 23 use the following::
dnf install docker
systemctl enable docker.service
@ -132,7 +158,7 @@ Mockup installation
#. Run ./buildImage.sh and ./run-redfish-simulator.sh
#. Check that a container is running and listening on port 8000::
(pypi)[uggla@ugglalaptop dmtf]$ docker ps
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9943ff1d4d93 redfish-simulator:latest "/bin/sh -c /tmp/redf" 3 weeks ago Up 2 days 0.0.0.0:8000->80/tcp redfish-simulator
#. Try to connect using a navigator to http://localhost:8000 the following screen should apear.
@ -145,14 +171,14 @@ Note : in the above screenshot, firefox JSON-handle extension is used. If you wa
Testing against the mockup
==========================
#. Follow `Host configuration file configuration`_ and `Mockup installation`_ section.
#. Follow `Inventory file configuration`_ and `Mockup installation`_ section.
#. Run the following command::
redfish-client manager getinfo
The result should be like this::
(pypi)[uggla@ugglalaptop dmtf]$ redfish-client manager getinfo
$ redfish-client manager getinfo
Gathering data from manager, please wait...
Redfish API version : 1.00
@ -206,10 +232,10 @@ The result should be like this::
Building local documentation
============================
Building the html documentation locally
Building the html documentation locally.
#. Follow `get the sources <http://pythonhosted.org/python-redfish/readme.html#get-the-sources>`_ section to retrieve the sources.
#. Follow `get the source code <http://pythonhosted.org/python-redfish/readme.html#get-the-source-code>`_ section to retrieve it.
#. Jump in the doc directory::
cd doc
@ -220,7 +246,7 @@ Building the html documentation locally
If you want to build the documentation in pdf.
#. Get texlive full distribution, ex on Fedora::
#. Get texlive full distribution, e.g. on Fedora 23::
dnf install texlive-scheme-full
#. Build the documentation::

6
doc/source/testing.rst
View File

@ -8,13 +8,13 @@ redfish module tests
Tests are not functional for the redfish module yet.
refish-client tests
-------------------
redfish-client tests
--------------------
#. Create your development environment following `Developer setup <develsetup.html>`_.
#. Install docker using the `procedure <https://docs.docker.com/engine/installation/>`_.
#. Ensure you can use docker with your current user.
#. Jump into redfish-python directory containing the sources.
#. Jump into the python-redfish directory containing the source code.
#. Depending of your distribution, you may have to upgrade setuptools::
pip install --upgrade setuptools

6
doc/source/usage.rst
View File

@ -11,8 +11,8 @@ redfish mockup.
Example using a proliant
------------------------
example/simple-proliant.py provide a simple library usage to interact with a HP
proliant BL460C G9 server. However this example should work on any server supplier following redfish
example/simple-proliant.py provide a simple library usage to interact with a HPE
ProLiant BL460C G9 server. However this example should work on any server supplier following redfish
standard.
redfish-client usage
@ -22,5 +22,5 @@ The client usage can be display using::
redfish-client -h
This is also available at http://pythonhosted.org/python-redfish/redfish-client.html .
This is also available at http://pythonhosted.org/python-redfish/redfish-client.html.

0
redfish/tests/__init__.py
View File

23
redfish/tests/base.py
View File

@ -1,23 +0,0 @@
# -*- coding: utf-8 -*-
# Copyright 2010-2011 OpenStack Foundation
# Copyright (c) 2013 Hewlett-Packard Development Company, L.P.
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
from oslotest import base
class TestCase(base.BaseTestCase):
"""Test case base class for all unit tests."""

122
redfish/tests/test_redfish.py
View File

@ -1,122 +0,0 @@
# -*- coding: utf-8 -*-
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""
test_redfish
----------------------------------
Tests for `redfish` module.
"""
import fixtures
import httplib
import json
import mock
import ssl
from redfish.tests import base
from redfish import server
from redfish import types
def get_fake_params(host=None, user=None, pword=None):
if not host:
host = 'https://127.0.0.1'
if not user:
user = 'admin'
if not pword:
pword = 'password'
return (host, user, pword)
def get_response():
class _response(object):
status = 200
def read(self):
return '{"foo": "bar"}'
def getheaders(self):
return [('Fake-Header', 'fake value')]
return _response()
class TestException(Exception):
pass
class TestRedfishConnection(base.TestCase):
def setUp(self):
super(TestRedfishConnection, self).setUp()
self.log_fixture = self.useFixture(fixtures.FakeLogger())
self.con_mock = mock.MagicMock()
self.con_mock.getresponse = get_response
self.http_mock = mock.patch.object(httplib, 'HTTPConnection').start()
self.http_mock.return_value = self.con_mock
self.https_mock = mock.patch.object(httplib, 'HTTPSConnection').start()
self.https_mock.return_value = self.con_mock
self.addCleanup(self.http_mock.stop)
self.addCleanup(self.https_mock.stop)
def test_create_ok(self):
con = server.RedfishConnection(*get_fake_params())
self.assertEqual(1, self.https_mock.call_count)
self.assertEqual(0, self.http_mock.call_count)
def test_create_calls_https_connect(self):
self.https_mock.side_effect = TestException()
self.assertRaises(TestException,
server.RedfishConnection,
*get_fake_params(host='https://fake'))
def test_create_calls_http_connect(self):
self.http_mock.side_effect = TestException()
self.assertRaises(TestException,
server.RedfishConnection,
*get_fake_params(host='http://fake'))
# TODO: add test for unknown connection schema (eg, ftp://)
# FIXME: ssl module has no attribute 'SSLContext'
# NOTE: skip this test if sys.version_info (major, minor) != (2, 7) and micro < 9
# @mock.patch.object(ssl, 'SSLContext')
# def test_insecure_ssl(self, ssl_mock):
# ssl_mock.return_value = mock.Mock()
# con = connection.RedfishConnection(*get_fake_params)
# ssl_mock.assert_called_once_with(ssl.PROTOCOL_TLSv1)
def test_get_ok(self):
con = server.RedfishConnection(*get_fake_params())
res = con.rest_get('/v1/test/', '')
self.assertEqual(200, con.status)
# Headers ae lower cased when returned
self.assertIn('fake-header', con.headers.keys())
self.assertIn('foo', res.keys())
self.con_mock.request.assert_called_with(
'GET', '/v1/test/', body='null', headers=mock.ANY)
# TODO: add test for redirects
# TODO: add test for collections
# TODO: add test for gzip'd body
def test_post_ok(self):
body = '{"fake": "body"}'
json_body = json.dumps(body)
con = server.RedfishConnection(*get_fake_params())
res = con.rest_post('/v1/test/', '', body)
self.assertEqual(200, con.status)
self.con_mock.request.assert_called_with(
'POST', '/v1/test/', body=json_body, headers=mock.ANY)