diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index f7e62ed..1e21a5d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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. diff --git a/README.rst b/README.rst index cb69f58..4aba520 100644 --- a/README.rst +++ b/README.rst @@ -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 diff --git a/doc/source/develsetup.rst b/doc/source/develsetup.rst index 551a3fd..64d9dcb 100644 --- a/doc/source/develsetup.rst +++ b/doc/source/develsetup.rst @@ -2,7 +2,7 @@ Developer setup =============== -#. Follow `get the sources `_ section to retrieve the sources. +#. Follow `get the source code `_ section to retrieve the sources. #. Follow `using pip and virtualenv `_ section to create your environment. You can start hacking the code now. diff --git a/doc/source/help.rst b/doc/source/help.rst index e229349..db643ab 100644 --- a/doc/source/help.rst +++ b/doc/source/help.rst @@ -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. diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 2698e3f..4c7440d 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -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 `_ section to retrieve the sources. -#. Install from the source using:: +#. Follow `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 `_ tool. -#. Follow `get the sources `_ section to retrieve the sources. +#. Follow `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 `_ 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 `_ 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 `_ section to retrieve the sources. -#. Install docker using your distribution packages or the docker `procedure `_ (docker provide more recent packages for ubuntu):: +#. Follow `get the source code `_ section to retrieve it. +#. Install docker using your distribution packages or the docker `procedure `_ (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 `_ section to retrieve the sources. +#. Follow `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:: diff --git a/doc/source/testing.rst b/doc/source/testing.rst index 947b1b6..e8f2788 100644 --- a/doc/source/testing.rst +++ b/doc/source/testing.rst @@ -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 `_. #. Install docker using the `procedure `_. #. 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 diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 9bc79e3..1f8d19f 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -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. diff --git a/redfish/tests/__init__.py b/redfish/tests/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/redfish/tests/base.py b/redfish/tests/base.py deleted file mode 100644 index 1c30cdb..0000000 --- a/redfish/tests/base.py +++ /dev/null @@ -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.""" diff --git a/redfish/tests/test_redfish.py b/redfish/tests/test_redfish.py deleted file mode 100644 index b70b43b..0000000 --- a/redfish/tests/test_redfish.py +++ /dev/null @@ -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)