Bug 1259293 - Missing documentation of the Python "API"
Missing documentation of the Python "API"
Status: CLOSED NOTABUG
Product: Copr
Classification: Community
Component: frontend (Show other bugs)
unspecified
Unspecified Unspecified
unspecified Severity high
: ---
: ---
Assigned To: Miroslav Suchý
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2015-09-02 07:36 EDT by Radek Holy
Modified: 2016-01-27 08:17 EST (History)
1 user (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2016-01-27 08:17:44 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Radek Holy 2015-09-02 07:36:02 EDT
If I did not miss something, the Python "API" is currently documented just using some incomplete examples. Or what else do you consider a documentation? I believe it is not possible to speak about API until it is properly documented.

Let me provide some examples of what I think that is missing:

* It is not clear what type of strings the interface expect. Looking into the code, it seems that in Python 2, the Unicode strings are expected.
* It is not clear whether I can reliably use stuff like "project.data['detail']['yum_repos']".
* It is not clear whether I can reliably configure the "Instructions", "Homepage", "Contact" and "External Repositories" using the "cl.create_project" method.
* It is not clear what happens if I pass wrong credentials or if an Internet connection is not available or if a project or build cannot be created.
* It is not clear that I can pass local paths to "cl.create_new_build".
* It is not clear whether I can reliably use "build.handle.get_build_details().results".
* It is not clear whether I can reliably use "cl.get_project_details(name)".
Comment 1 Miroslav Suchý 2015-09-03 05:26:01 EDT
Valentin, can you please address that during APIv2 work?
Comment 2 Valentin Gologuzov 2015-09-03 07:18:46 EDT
You probably could find a bit more in the autodoc section:
http://python-copr.readthedocs.org/en/latest/CoprClient.html
http://python-copr.readthedocs.org/en/latest/Responses.html

Some of your questions is answered there.
Comment 3 Radek Holy 2015-09-10 09:40:20 EDT
Thank you. I apologize that I've missed the autodoc section.

I'll just add some other examples I hit during writing my scripts in case it is useful (don't worry, I'm not going to add more):

* It is not clear what happens if:
    - the configuration file is not readable or if it is not valid
    - if I call `cl.create_project` on an existing project
    - if I call `cl.delete_project` on a non-existent project
    - if I call `cl.get_project_details` on a non-existent project

Note You need to log in before you can comment on or make changes to this bug.