===============
The README File
===============

Background
==========
This project is a result of collecting some basic boilerplate code that
I was commonly using for Python scripts interfacing with the `Open Build
Service <http://openbuildservice.org/>`_. The goal is to create a pythonic
interface to OBS which is a pleasure to work with.

Quickstart
==========

Initialize api connection. *(will use credentials from existing .oscrc or .netrc files)*

.. code-block:: python

   >>> from obsapi import ObsApi
   >>> api = ObsApi('https://api.opensuse.org')

Get a list of all projects.

.. code-block:: python

   >>> api.ls()
   ['Apache',
    'Apache:MirrorBrain',
    'Apache:Modules',
    'Apache:Next',
    'Apache:Shibboleth',
    'Apache:Test',
    'Application:Dochazka',
    'Application:EJBCA',
    'Application:ERP',
    'Application:ERP:Dolibarr',
    'Application:ERP:GNUHealth',
    'Application:ERP:GNUHealth:3.2',
   ...

Get a list of packages in project:

.. code-block:: python

   >>> api.ls('Apache')
   ['apache-rex',
    'apache-rpm-macros',
    'apache-rpm-macros-control',
    'apache2',
    'apache2-icons-oxygen',
    'apr',
    'apr-util',
    'brotli',
    'cronolog',
    'flood',
    'vlogger']


Get the list of source files in an OBS package:

.. code-block:: python

    >>> directory, listing = api.ls('Apache', 'apache2')
    >>> for file_item in listing:
    >>>     print(file_item.name)
    SUSE-NOTICE
    a2enflag
    a2enmod
    apache-22-24-upgrade
    apache-ssl-stuff.tar.bz2
    apache2-README
    apache2-README-access_compat.txt
    apache2-README-instances.txt
    apache2-README.QUICKSTART
    apache2-check_forensic
    apache2-default-server.conf

Get list of repos configured in the project

.. code-block:: python

    >>> api.get_project_repos('Apache')
    ['openSUSE_Tumbleweed',
     'openSUSE_Leap_15.1',
     'openSUSE_Leap_15.0',
     'openSUSE_Factory',
     'SLE_15_SP1',
     'SLE_15',
     'SLE_12_SP4',
     'SLE_12_SP3',
     'SLE_12_SP2',
     'SLE_12_SP1',
     'SLE_11_SP4',
     'SLE_11_SP3']

Get list of repos configured in the project

.. code-block:: python

    >>> api.ls('Apache', 'apache2', 'openSUSE_Tumbleweed', 'x86_64')
    [Binary(filename='_buildenv', size='24965', mtime='1580719264'),
     Binary(filename='_statistics', size='958', mtime='1580719264'),
     Binary(filename='apache2-2.4.41-12.1.src.rpm', size='7657917', mtime='1580719265'),
     Binary(filename='apache2-2.4.41-12.1.x86_64.rpm', size='1239972', mtime='1580719265'),
     Binary(filename='apache2-debuginfo-2.4.41-12.1.x86_64.rpm', size='2118372', mtime='1580719265'),
    ...

Access details of the binaries:

.. code-block:: python

    >>> for binary in api.ls('Apache', 'apache2', 'openSUSE_Tumbleweed', 'x86_64'):
            print('file: {}, size: {}'.format(binary.filename, binary.size))
    file: _buildenv, size: 24965
    file: _statistics, size: 958
    file: apache2-2.4.41-12.1.src.rpm, size: 7657917
    file: apache2-2.4.41-12.1.x86_64.rpm, size: 1239972
    file: apache2-debuginfo-2.4.41-12.1.x86_64.rpm, size: 2118372
    file: apache2-debugsource-2.4.41-12.1.x86_64.rpm, size: 1606596
    file: apache2-devel-2.4.41-12.1.x86_64.rpm, size: 416400
    ...


Low level interfaces
====================

The obsapi library has set of classes that implement a low level,
thin wrapper around the OBS server api. The OBS api is split into
dedicated classes for the toplevel API paths like ``build``, ``source``,
``request``, ``attribute`` etc. Currently only the ``build`` and ``source``
APIs are implemented.

The base API classes are named using the following scheme:

``Obs<API_PATH>Api``

For example:

``ObsBuildApi``: serves all ``/build/*`` based API calls

``ObsSourceApi``: serves all ``/source/*`` based API calls


Simple GET, PUT, POST commands
------------------------------

The base API classes implement ``get``, ``put``, ``post`` methods for each
corresponding API call. The arguments to the methods match the arguments
to the OBS API paths. For example from the OBS apidocs we have a GET API
to get a source listing of the package. The schema is documented as follows::

    GET /source/<project>/<package>

The ObsSourceApi class implements the corresponding method in a 1:1 fashion:

.. code-block:: python

   ObsSourceApi.get(project, package)

Underscored API elements
------------------------
For API calls that contain a ``_``\ *specifier* type syntax like::

    GET /source/<project>/<package>/_meta

the corresponding class method name is extended with the ``_``\ *specifier* as follows::

    ObsSourceApi.get_meta(project, package)

Some OBS API calls have an underscored element surrounded by path arguments like::

    GET /source/<project>/<package>/_attribute/<attribute>

In this case the arguments are still passed to the method call in the order
that they appear in URL specification::

   ObsSourceApi.get_attribute(project, package, attribute)

Note again that the ``_attribute`` element in this case becomes part of the method
name. The ``GET``, ``POST``, ``DELETE`` calls for the ``_attribute`` API are translated
to ``get_attribute``, ``post_attribute``, and ``delete_attribute`` accordingly.

For API calls that take HTTP query arguments, simply add the argument as a standard
keyword argument at the end of the method call. For example::

    POST /source/<project>/<package>?cmd=unlock

maps to::

    ObsSourceApi.post(project, package, cmd='unlock')

Order of positional arguments
-----------------------------
The arguments of the class methods have a positional ordering that follows the
sequence of the OBS API URL parts. Of course the method argument positions can be
changed by passing the arguments in a keyword fashion. For Example::

    ObsSourceApi.post(mypackage, mypoject, cmd='unlock')

can be called like::

    ObsSourceApi.post(pkg=mypackage, prj=mypoject, cmd='unlock')

The names of the method arguments follow the names specified in the OBS
API docs except for ``project`` and ``package`` arguments which are
abbreviated to ``prj`` and ``pkg``.