Repository :
http://git.fedorahosted.org/cgit/copr.git
On branch : master
---------------------------------------------------------------
commit d97dc9ab65dedef19dfc5181eb9c6927e5681f68
Author: Valentin Gologuzov <vgologuz(a)redhat.com>
Date: Wed Nov 18 16:19:48 2015 +0100
[python][WIP] documentation for ClientV2: done with Project Chroot
---------------------------------------------------------------
python/copr/client_v2/handlers.py | 41 ++++++++---
python/copr/client_v2/resources.py | 22 ++++--
python/docs/ClientV2.rst | 2 +-
python/docs/client_v2/entities.rst | 10 +++
python/docs/client_v2/handlers.rst | 19 ++++-
python/docs/client_v2/resource_info/project.rst | 36 ++++++----
.../client_v2/resource_info/project_chroot.rst | 76 +++++++++++++++++++-
python/docs/client_v2/resources.rst | 20 +++++-
8 files changed, 187 insertions(+), 39 deletions(-)
diff --git a/python/copr/client_v2/handlers.py b/python/copr/client_v2/handlers.py
index d52653c..b677946 100644
--- a/python/copr/client_v2/handlers.py
+++ b/python/copr/client_v2/handlers.py
@@ -279,9 +279,13 @@ class ProjectChrootHandle(AbstractHandle):
return "{}{}".format(self.root_url,
project.get_href_by_name("chroots"))
def get_one(self, project, name):
- """
- :type project: copr.client_v2.resources.Project
+ """ Retrieves project chroot object.
+
+ :type project: :py:class:`~copr.client_v2.resources.Project`
+ :param project: parent project for the chroot
:param str name: chroot name
+
+ :rtype: :py:class:`~copr.client_v2.resources.ProjectChroot`
"""
url = "{}/{}".format(self.get_base_url(project), name)
@@ -295,8 +299,12 @@ class ProjectChrootHandle(AbstractHandle):
)
def get_list(self, project):
- """
- :type project: copr.client_v2.resources.Project
+ """ Retrieves project chroot list object.
+
+ :type project: :py:class:`~copr.client_v2.resources.Project`
+ :param project: parent project for the chroot
+
+ :rtype: :py:class:`~copr.client_v2.resources.ProjectChrootList`
"""
response = self.nc.request(self.get_base_url(project))
return ProjectChrootList.from_response(
@@ -306,8 +314,11 @@ class ProjectChrootHandle(AbstractHandle):
)
def disable(self, project, name):
- """
- :type project: copr.client_v2.resources.Project
+ """ Disables one chroot for the project
+
+ :type project: :py:class:`~copr.client_v2.resources.Project`
+ :param project: parent project for the chroot
+
:param str name: chroot name to disable
"""
url = "{}/{}".format(self.get_base_url(project), name)
@@ -315,10 +326,17 @@ class ProjectChrootHandle(AbstractHandle):
return OperationResult(self, response)
def enable(self, project, name, buildroot_pkgs=None):
- """
- :type project: copr.client_v2.resources.Project
+ """ Enables one chroot for the project
- :rtype:
+ :type project: :py:class:`~copr.client_v2.resources.Project`
+ :param project: parent project for the chroot
+
+ :param str name: chroot name to enable
+
+ :params buildroot_pkgs: packages to add into the buildroot
+ :type buildroot_pkgs: list of str
+
+ :rtype: :py:class:`.OperationResult`
"""
new_entity = ProjectChrootEntity(
@@ -336,7 +354,10 @@ class ProjectChrootHandle(AbstractHandle):
def update(self, project, chroot_entity):
"""
:type project: copr.client_v2.resources.Project
- :type chroot_entity: copr.client_v2.entities.ProjectChrootEntity
+ :param chroot_entity: Entity to update
+ :type chroot_entity: :py:class:`.entities.ProjectChrootEntity`
+
+ :rtype: :py:class:`.OperationResult`
"""
url = "{}/{}".format(self.get_base_url(project), chroot_entity.name)
response = self.nc.request(
diff --git a/python/copr/client_v2/resources.py b/python/copr/client_v2/resources.py
index b006a39..58a9cda 100644
--- a/python/copr/client_v2/resources.py
+++ b/python/copr/client_v2/resources.py
@@ -149,21 +149,21 @@ class Project(IndividualResource):
Shortcut for for :py:meth:`.ProjectHandle.update`
- :rtype: :py:class:`~copr.client_v2.resources.OperationResult`
+ :rtype: :py:class:`.OperationResult`
"""
return self._handle.update(self._entity)
def delete(self):
""" Updates project using the current state
- :rtype: :py:class:`~copr.client_v2.resources.OperationResult`
+ :rtype: :py:class:`.OperationResult`
"""
return self._handle.delete(self.id)
def get_self(self):
""" Retrieves fresh project object from the service
- :rtype: :py:class:`~copr.client_v2.resources.Project`
+ :rtype: :py:class:`.Project`
"""
return self._handle.get_one(self.id)
@@ -180,7 +180,7 @@ class Project(IndividualResource):
""" Retrieves project chroot object by the given name
:param str name: mock chroot name
- :rtype: :py:class:`~copr.client_v2.resources.ProjectChroot`
+ :rtype: :py:class:`.ProjectChroot`
"""
handle = self._handle.get_project_chroots_handle()
return handle.get_one(self, name)
@@ -188,7 +188,7 @@ class Project(IndividualResource):
def get_project_chroot_list(self):
""" Retrieves project chroots list
- :rtype: :py:class:`~copr.client_v2.resources.ProjectChrootList`
+ :rtype: :py:class:`.ProjectChrootList`
"""
handle = self._handle.get_project_chroots_handle()
return handle.get_list(self)
@@ -197,8 +197,10 @@ class Project(IndividualResource):
"""
Enables given chroot for this project
+ Shortcut for for :py:meth:`.ProjectChrootHandle.enable`
+
:param str name: mock chroot name
- :rtype: :py:class:`~copr.client_v2.resources.OperationResult`
+ :rtype: :py:class:`.OperationResult`
"""
handle = self._handle.get_project_chroots_handle()
return handle.enable(self, name)
@@ -249,9 +251,17 @@ class ProjectChroot(IndividualResource):
response=response, links=links, options=options)
def disable(self):
+ """ Disables chroot for the bound project
+
+ :rtype: :py:class:`.OperationResult`
+ """
return self._handle.disable(self._project, self.name)
def update(self):
+ """ Updates chroot with the current entity state
+
+ :rtype: :py:class:`.OperationResult`
+ """
return self._handle.update(self._project, self._entity)
diff --git a/python/docs/ClientV2.rst b/python/docs/ClientV2.rst
index 413a070..93e80c9 100644
--- a/python/docs/ClientV2.rst
+++ b/python/docs/ClientV2.rst
@@ -30,7 +30,6 @@ Resources info
client_v2/resource_info/build.rst
client_v2/resource_info/mock_chroot.rst
-
Autodoc
-------
@@ -39,3 +38,4 @@ Autodoc
client_v2/general.rst
client_v2/handlers.rst
client_v2/resources.rst
+ client_v2/entities.rst
diff --git a/python/docs/client_v2/entities.rst b/python/docs/client_v2/entities.rst
new file mode 100644
index 0000000..0bf4d2a
--- /dev/null
+++ b/python/docs/client_v2/entities.rst
@@ -0,0 +1,10 @@
+Entities
+========
+
+Represents domain objects like project or build.
+The user of ``python-copr`` is not expected to use the directly.
+
+.. automodule:: copr.client_v2.entities
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/python/docs/client_v2/handlers.rst b/python/docs/client_v2/handlers.rst
index 4df33c0..0ba9293 100644
--- a/python/docs/client_v2/handlers.rst
+++ b/python/docs/client_v2/handlers.rst
@@ -1,18 +1,31 @@
Handlers
========
+Project
+-------
.. autoclass:: copr.client_v2.handlers.ProjectHandle
:members: get_list, get_one, update, delete
- :undoc-members:
+Project chroot
+--------------
.. autoclass:: copr.client_v2.handlers.ProjectChrootHandle
- :members: get_list, get_one
- :undoc-members:
+ :members: get_list, get_one, enable, update, disable
+Build
+-----
.. autoclass:: copr.client_v2.handlers.BuildHandle
:members:
+Build task
+----------
+
+.. note::
+ Not implemented yet
+
+
+Mock chroot
+-----------
.. autoclass:: copr.client_v2.handlers.MockChrootHandle
:members: get_list, get_one
:undoc-members:
diff --git a/python/docs/client_v2/resource_info/project.rst
b/python/docs/client_v2/resource_info/project.rst
index 2758c08..76a9b14 100644
--- a/python/docs/client_v2/resource_info/project.rst
+++ b/python/docs/client_v2/resource_info/project.rst
@@ -1,13 +1,18 @@
+
+.. _project-info:
+
Project
=======
-Access to project resources is done through
:py:meth:`~copr.client_v2.client.CoprClient.projects`.
+Access to the projects is done through
:py:meth:`~copr.client_v2.client.CoprClient.projects`.
property of initialized :py:class:`~copr.client_v2.client.CoprClient`. That property is
an instance of
:py:class:`~copr.client_v2.handlers.ProjectHandle`. Projects are represented by
:py:class:`~copr.client_v2.resources.Project` class.
-Individual Attributes
----------------------
+.. _project-attributes:
+
+Project entity attributes
+-------------------------
.. copied from frontend docs, don't forget to update
@@ -34,6 +39,19 @@ repos list of string yes list of additional
repositori
all following examples assume that we use ``cl``
as an instance of :py:class:`.client_v2.client.CoprClient`
+
+Get projects list
+-----------------
+
+.. sourcecode:: python
+
+ >>> plist_1 = cl.project.get_list(limit=10)
+ # filter by name
+ >>> plist_2 = cl.project.get_list(name="copr")
+ # search by string
+ >>> plist_2 = cl.project.get_list(name="copr")
+
+
Get one project
---------------
@@ -62,18 +80,6 @@ Create new project
.. note:: Not Implemented yet
-Fetch projects
---------------
-
-.. sourcecode:: python
-
- >>> plist_1 = cl.project.get_list(limit=10)
- # filter by name
- >>> plist_2 = cl.project.get_list(name="copr")
- # search by string
- >>> plist_2 = cl.project.get_list(name="copr")
-
-
Access project chroots
----------------------
.. note::
diff --git a/python/docs/client_v2/resource_info/project_chroot.rst
b/python/docs/client_v2/resource_info/project_chroot.rst
index 8920b02..033919d 100644
--- a/python/docs/client_v2/resource_info/project_chroot.rst
+++ b/python/docs/client_v2/resource_info/project_chroot.rst
@@ -4,6 +4,80 @@
Project chroot
==============
-foobar
+Access to the project chroots is done through
:py:meth:`~copr.client_v2.client.CoprClient.project_chroots`.
+property of initialized :py:class:`~copr.client_v2.client.CoprClient`. That property is
an instance of
+:py:class:`~copr.client_v2.handlers.ProjectChrootHandle`.
+
+However it's usually more convenient to access project chroots
+from an instance of :py:class:`~copr.client_v2.resources.Project`
+using methods :py:meth:`~copr.client_v2.resources.Project.get_project_chroot_list` or
+:py:meth:`~copr.client_v2.resources.Project.get_project_chroot`.
+
+Chroot are represented by
+:py:class:`~copr.client_v2.resources.ProjectChroot` class.
+
+.. _project-chroot-attributes:
+
+Entity Attributes
+-----------------
+
+.. copied from frontend docs, don't forget to update
+
+================== ==================== ========= ===============
+Field Type Can edit? Description
+================== ==================== ========= ===============
+name string no chroot name
+buildroot_pkgs list of strings yes packages to be installed into the
buildroot
+comps string yes content of the `comps.xml`_
+comps_name string yes name of the uploaded comps file
+comps_len int no size of the uploaded comps file
(bytes)
+================== ==================== ========= ===============
+
+.. note::
+ all following examples assume that we use ``cl``
+ as an instance of :py:class:`.client_v2.client.CoprClient`
+ and ``p`` as an instance of :py:class:`~copr.client_v2.resources.Project`
+
+Get project chroots list
+------------------------
+
+.. sourcecode:: python
+
+ >>> pc_list = cl.project_chroots.get_list(project=p)
+ # or more simple
+ >>> pc_list = p.get_project_chroot_list()
+ >>> map(str, pc_list)
+ ['<Project chroot: fedora-21-x86_64, additional packages: [], comps size if
any: 0>',
+ '<Project chroot: epel-7-x86_64, additional packages: [], comps size if any:
0>']
+
+
+Get one project chroot
+----------------------
+
+.. sourcecode:: python
+
+
+ >>> pc = cl.project_chroots.get_one(project=p,
name="fedora-23-x86_64")
+ # or
+ >>> pc = p.get_project_chroot("fedora-23-x86_64")
+ >>> print(pc)
+ <Project chroot: fedora-23-x86_64, additional packages: [], comps size if any:
0>
+
+Modify project chroot
+---------------------
+
+.. sourcecode:: python
+
+ >>> pc.buildroot_pkgs = ["scl-utils",]
+ >>> pc.update()
+
+Disable project chroot
+----------------------
+.. sourcecode:: python
+
+ >>> pc.disable()
+
+
+.. _comps.xml:
https://fedorahosted.org/comps/
diff --git a/python/docs/client_v2/resources.rst b/python/docs/client_v2/resources.rst
index f19c5fc..7e721b6 100644
--- a/python/docs/client_v2/resources.rst
+++ b/python/docs/client_v2/resources.rst
@@ -1,28 +1,42 @@
Resources
=========
+Project
+-------
+see entity attributes here: :ref:`project-attributes`.
+
.. autoclass:: copr.client_v2.resources.Project
:members:
.. autoclass:: copr.client_v2.resources.ProjectList
:members:
+Project chroot
+--------------
.. autoclass:: copr.client_v2.resources.ProjectChroot
:members:
-
.. autoclass:: copr.client_v2.resources.ProjectChrootList
:members:
+Build
+-----
+.. autoclass:: copr.client_v2.resources.Build
+ :members:
-.. autoclass:: copr.client_v2.resources.MockChroot
+.. autoclass:: copr.client_v2.resources.BuildList
:members:
+Mock chroot
+-----------
+.. autoclass:: copr.client_v2.resources.MockChroot
+ :members:
.. autoclass:: copr.client_v2.resources.MockChrootList
:members:
-
+Operation result
+----------------
.. autoclass:: copr.client_v2.resources.OperationResult
:members: