Update README

1 files changed, 205 insertions, 0 deletions

diff --git a/README.rst b/README.rst
index 948e570..f8139fc 100644
--- a/README.rst
+++ b/README.rst
@@ -1,2 +1,207 @@
+===============
 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``.
+