Repository :
http://git.fedorahosted.org/cgit/copr.git
On branch : master
---------------------------------------------------------------
commit e28cfc5af3a38746a6627bdf7ec0078a52e99f96
Author: Valentin Gologuzov <vgologuz(a)redhat.com>
Date: Wed Nov 18 17:38:50 2015 +0100
[python][WIP] documentation for ClientV2: done with Builds
---------------------------------------------------------------
python/copr/client_v2/handlers.py | 67 +++++++++-----
python/copr/client_v2/resources.py | 23 +++++
python/docs/ClientV2.rst | 1 +
python/docs/client_v2/resource_info/build.rst | 97 +++++++++++++++++++-
python/docs/client_v2/resource_info/build_task.rst | 6 +
python/docs/client_v2/resource_info/project.rst | 1 -
.../client_v2/resource_info/project_chroot.rst | 4 +-
python/docs/client_v2/resources.rst | 4 +
8 files changed, 175 insertions(+), 28 deletions(-)
diff --git a/python/copr/client_v2/handlers.py b/python/copr/client_v2/handlers.py
index b677946..6f934c7 100644
--- a/python/copr/client_v2/handlers.py
+++ b/python/copr/client_v2/handlers.py
@@ -37,8 +37,10 @@ class BuildHandle(AbstractHandle):
return self._base_url
def get_one(self, build_id):
- """
- :type build_id: int
+ """ Retrieves builds object
+
+ :param int build_id: id of the target build
+ :rtype: :py:class:`~.resources.Build`
"""
options = {"build_id": build_id}
@@ -52,12 +54,14 @@ class BuildHandle(AbstractHandle):
)
def get_list(self, project_id=None, owner=None, limit=None, offset=None):
- """
- :param owner:
- :param project_id:
- :param limit:
- :param offset:
- :rtype: BuildList
+ """ Retrieves builds object according to the given parameters
+
+ :param owner: name of the project owner
+ :param project_id: id of the project
+ :param limit: limit number of builds
+ :param offset: number of builds to skip
+
+ :rtype: :py:class:`~.resources.BuildList`
"""
options = {
"project_id": project_id,
@@ -70,8 +74,12 @@ class BuildHandle(AbstractHandle):
return BuildList.from_response(self, response, options)
def cancel(self, build_entity):
- """
- :type build_entity: copr.client_v2.entities.BuildEntity
+ """ Cancels the given build
+
+ :param build_entity: build entity to delete
+ :type build_entity: :py:class:`~.copr.client_v2.entities.BuildEntity
+
+ :rtype: :py:class:`.OperationResult`
"""
build_id = build_entity.id
build_entity.state = "canceled"
@@ -81,6 +89,13 @@ class BuildHandle(AbstractHandle):
return OperationResult(self, response)
def delete(self, build_id):
+ """ Deletes the given build
+
+ :param int build_id: build id to delete
+
+ :rtype: :py:class:`.OperationResult`
+ """
+
url = "{}/{}".format(self.get_base_url(), build_id)
response = self.nc.request(url, method="delete", do_auth=True)
return OperationResult(self, response, expected_status=204)
@@ -106,16 +121,15 @@ class BuildHandle(AbstractHandle):
"""
Creates new build using public url to the srpm file
- :param int project_id:
- :param str srpm_url:
- :param str file_name:
- :param list chroots:
- :param bool enable_net:
+ :param int project_id: id of the project where we want to submit new build
+ :param str srpm_url: url to the source rpm
+ :param list chroots: which chroots should be used during the build
+ :param bool enable_net: allows to disable network access during the build,
default: True
+
:return: created build
- :rtype: Build
+ :rtype: :py:class:`~.resources.Build`
"""
-
chroots = map(str, chroots or list())
content = {
"project_id": int(project_id),
@@ -131,20 +145,25 @@ class BuildHandle(AbstractHandle):
return self._process_create_response(data, response)
- def create_from_file(self, project_id, file_path=None, file_obj=None,
file_name=None,
+ def create_from_file(self, project_id, file_path=None,
+ file_obj=None, file_name=None,
chroots=None, enable_net=True):
"""
Creates new build using srpm upload, please specify
either `file_path` or (`file_obj`, `file_name).
- :param int project_id:
+ :param int project_id: id of the project where we want to submit new build
+
:param str file_path: path to the srpm file
- :param file like object file_obj:
- :param str file_name:
- :param list chroots:
- :param bool enable_net:
+
+ :param file file_obj: file-like object to read from
+ :param str file_name: name for the uploaded file
+
+ :param list chroots: which chroots should be used during the build
+ :param bool enable_net: allows to disable network access during the build,
default: True
+
:return: created build
- :rtype: Build
+ :rtype: :py:class:`~.resources.Build`
"""
chroots = map(str, chroots or list())
diff --git a/python/copr/client_v2/resources.py b/python/copr/client_v2/resources.py
index 58a9cda..fdd0f16 100644
--- a/python/copr/client_v2/resources.py
+++ b/python/copr/client_v2/resources.py
@@ -122,12 +122,24 @@ class Build(IndividualResource):
response=response, links=links, options=options)
def get_self(self):
+ """ Retrieves fresh build object from the service
+
+ :rtype: :py:class:`~.Build`
+ """
return self._handle.get_one(self.id)
def cancel(self):
+ """ Updates the current build
+
+ :rtype: :py:class:`.OperationResult`
+ """
return self._handle.cancel(self._entity)
def delete(self):
+ """ Deletes the current build
+
+ :rtype: :py:class:`.OperationResult`
+ """
return self._handle.delete(self.id)
@@ -436,8 +448,19 @@ class BuildList(CollectionResource):
super(BuildList, self).__init__(**kwargs)
self._handle = handle
+ def next_page(self):
+ """
+ Retrieves next chunk of the Build list for the same query options
+
+ :rtype: :py:class:`.BuildList`
+ """
+ return super(BuildList, self).next_page()
+
@property
def builds(self):
+ """
+ :rtype: :py:class:`.BuildList`
+ """
return self._individuals
@classmethod
diff --git a/python/docs/ClientV2.rst b/python/docs/ClientV2.rst
index 93e80c9..7d9d36f 100644
--- a/python/docs/ClientV2.rst
+++ b/python/docs/ClientV2.rst
@@ -28,6 +28,7 @@ Resources info
client_v2/resource_info/project.rst
client_v2/resource_info/project_chroot.rst
client_v2/resource_info/build.rst
+ client_v2/resource_info/build_task.rst
client_v2/resource_info/mock_chroot.rst
Autodoc
diff --git a/python/docs/client_v2/resource_info/build.rst
b/python/docs/client_v2/resource_info/build.rst
index 924dc66..04880ee 100644
--- a/python/docs/client_v2/resource_info/build.rst
+++ b/python/docs/client_v2/resource_info/build.rst
@@ -3,4 +3,99 @@
Build
=====
-pass
+
+Access to the builds is done through
:py:meth:`~copr.client_v2.client.CoprClient.builds`.
+property of initialized :py:class:`~copr.client_v2.client.CoprClient`. That property is
an instance of
+:py:class:`~copr.client_v2.handlers.BuildHandle`.
+
+It may be more convenient to access builds in context of a project
+using method :py:meth:`~copr.client_v2.resources.Project.get_builds`.
+
+Builds are represented by
+:py:class:`~copr.client_v2.resources.Build` class.
+
+.. _build-attributes:
+
+Build entity attributes
+-----------------------
+
+.. copied from frontend docs, don't forget to update
+
+================== ==================== ===============
+Field Type Description
+================== ==================== ===============
+id int unique build identifier
+state string current state of the build, value is aggregated
from build tasks
+submitted_on int(unixtime UTC) time of the build submission
+started_on int(unixtime UTC) time when the first build task started,
otherwise ``null``
+ended_on int(unixtime UTC) time when the last build task ended, otherwise
``null``
+source_type string method used for build creation
+source_metadata json object build source information
+package_version string version of the source package
+package_name string name of the source package
+enable_net bool defines if network is available during the
build
+repos list of string list of additional repositories enabled during
the build
+built_packages list of hash maps list of the built packages, each hash map has
two keys: ``name`` and ``version``
+submitter string name of the user who submitted the build
+================== ==================== ===============
+
+.. note::
+ Only the ``state`` field is editable by the PUT method.
+ All other fields are read-only.
+
+Get builds list
+---------------
+
+.. sourcecode:: python
+
+ >>> blist_1 = cl.builds.get_list(limit=2)
+ >>> print(map(str, blist_1))
+ ['<Build #138426 state: succeeded>', '<Build #138425 state:
succeeded>']
+ # using the project object
+ >>> blist_2 = p.get_builds(limit=2)
+ >>> print(map(str, blist_2))
+ ['<Build #138423 state: failed>', '<Build #138421 state:
failed>']
+
+
+Get one build
+-------------
+
+.. sourcecode:: python
+
+ >>> b = cl.builds.get_one(138421)
+ >>> print(b)
+ <Build #138421 state: failed>
+
+
+Create new build
+----------------
+
+.. sourcecode:: python
+
+ # using the url to sprm
+ >>> b1 = cl.builds.create_from_url(project_id=3806,
srpm_url="http://example.com/my.src.rpm")
+ # or using project object
+ >>> b2 =
p.create_build_from_url("http://example.com/my.src.rpm")
+ >>> print(map(str, [b1, b2]))
+ ['<Build #138431 state: importing>', '<Build #138430 state:
importing>']
+
+ # and using the file upload
+ >>> b3 = cl.builds.create_from_file(project_id=3806,
file_path="/tmp/hello-2.8-1.fc20.src.rpm")
+ >>> b4 =
p.create_build_from_file("/tmp/hello-2.8-1.fc20.src.rpm")
+
+
+
+Cancel build
+------------
+
+.. sourcecode:: python
+
+ >>> b1.cancel()
+
+Delete build
+------------
+
+
+.. sourcecode:: python
+
+ >>> b1.delete()
diff --git a/python/docs/client_v2/resource_info/build_task.rst
b/python/docs/client_v2/resource_info/build_task.rst
new file mode 100644
index 0000000..f17a444
--- /dev/null
+++ b/python/docs/client_v2/resource_info/build_task.rst
@@ -0,0 +1,6 @@
+.. _build-task-info:
+
+Build task
+==========
+
+.. note:: Not implement yet
diff --git a/python/docs/client_v2/resource_info/project.rst
b/python/docs/client_v2/resource_info/project.rst
index 76a9b14..768d4bd 100644
--- a/python/docs/client_v2/resource_info/project.rst
+++ b/python/docs/client_v2/resource_info/project.rst
@@ -1,4 +1,3 @@
-
.. _project-info:
Project
diff --git a/python/docs/client_v2/resource_info/project_chroot.rst
b/python/docs/client_v2/resource_info/project_chroot.rst
index 033919d..ae59c75 100644
--- a/python/docs/client_v2/resource_info/project_chroot.rst
+++ b/python/docs/client_v2/resource_info/project_chroot.rst
@@ -18,8 +18,8 @@ Chroot are represented by
.. _project-chroot-attributes:
-Entity Attributes
------------------
+Project chroot entity attributes
+--------------------------------
.. copied from frontend docs, don't forget to update
diff --git a/python/docs/client_v2/resources.rst b/python/docs/client_v2/resources.rst
index 7e721b6..03abc45 100644
--- a/python/docs/client_v2/resources.rst
+++ b/python/docs/client_v2/resources.rst
@@ -13,6 +13,8 @@ see entity attributes here: :ref:`project-attributes`.
Project chroot
--------------
+see entity attributes here: :ref:`project-chroot-attributes`.
+
.. autoclass:: copr.client_v2.resources.ProjectChroot
:members:
@@ -21,6 +23,8 @@ Project chroot
Build
-----
+see entity attributes here: :ref:`build-attributes`.
+
.. autoclass:: copr.client_v2.resources.Build
:members: