Metadata-Version: 1.1
Name: txkoji
Version: 0.8.0
Summary: Twisted API for Koji
Home-page: https://github.com/ktdreyer/txkoji
Author: Ken Dreyer
Author-email: ktdreyer@ktdreyer.com
License: MIT
Description: Async interface to Koji, using Twisted
        ======================================
        
        .. image:: https://travis-ci.org/ktdreyer/txkoji.svg?branch=master
                     :target: https://travis-ci.org/ktdreyer/txkoji
        
        .. image:: https://badge.fury.io/py/txkoji.svg
                     :target: https://badge.fury.io/py/txkoji
        
        Access Koji's XML-RPC API asynchronously (non-blocking) using the Twisted
        framework.
        
        This supports the GSSAPI or Client SSL login methods.
        
        Simple Example: Fetching a user's name
        --------------------------------------
        
        .. code-block:: python
        
            from txkoji import Connection
            from twisted.internet import defer
            from twisted.internet.task import react
        
        
            @defer.inlineCallbacks
            def example(reactor):
                koji = Connection('brew')
                # Fetch a user.
                # You may pass an ID or a krb principal here
                user = yield koji.getUser(3595)
                # user is a Munch (dict-like) object.
                print(user.name)
        
        
            if __name__ == '__main__':
                react(example)
        
        Connecting to a Koji Hub
        ------------------------
        
        To connect to a Koji hub, create a new ``txkoji.Connection`` instance.
        
        You must pass a string to the constructor. This string is a profile name. For
        example, if you call ``Connector('mykoji')``, then txkoji will search
        ``/etc/koji.conf.d/*.conf`` for the ``[mykoji]`` config section. This matches
        what the regular Koji client code does.
        
        Making XML-RPC calls
        --------------------
        
        Koji Hub is an XML-RPC server. You can call any method on the ``Connection``
        class instance and txkoji will treat it as an XML-RPC call to the hub. For
        example, this Twisted ``inlineCallbacks``-style code looks up information about
        a given task ID and tag ID:
        
        .. code-block:: python
        
            @defer.inlineCallbacks
            def example(reactor):
                koji = Connection('mykoji')
        
                task = yield koji.getTaskInfo(10000)
                print(task.method)  # "createImage"
        
                tag = yield koji.getTag(2000)
                print(tag.name)  # "foo-build"
        
        
        To learn the full Koji XML-RPC API::
        
          koji list-api
        
        You can also read the `koji source code <https://pagure.io/koji/>`_ to find
        out details about how each method works.
        
        
        Logging in
        ----------
        
        Your Koji hub must support GSSAPI or Client SSL authentication. You must have a
        valid Kerberos ticket or SSL keypair.
        
        .. code-block:: python
        
            @defer.inlineCallbacks
            def example(reactor):
                koji = Connection('mykoji')
        
                result = yield login()
                print(result)  # "True"
                print('session-id: %s' % koji.session_id)
        
                # "Who am I?"
                user = yield koji.getLoggedInUser()
                print(user)
        
        
        Caching long-lived object names
        -------------------------------
        
        Sometimes all you have is a user id number or tag id number, and you want the
        user's name or tag's name instead.
        
        txkoji includes a read-through cache for obtaining the user name or tag name.
        See ``examples/cache.py`` for an example. txkoji's cache module stores its data
        in a ``txkoji`` subdirectory of the location specified with the
        ``$XDG_CACHE_HOME`` environment variable if that is set. It will fall back to
        using ``~/.cache/txkoji`` if the ``$XDG_CACHE_HOME`` environment variable is
        not set.
        
        
        Rich objects
        ------------
        
        The following RPC methods will return special classes that inherit from the
        Munch class:
        
        * ``getBuild`` returns ``txkoji.build.Build``
        * ``listBuilds`` returns a ``list`` of ``txkoji.build.Build``
        * ``getTaskInfo`` returns ``txkoji.task.Task``
        * ``getPackage`` returns ``txkoji.package.Package``
        
        These classes have their own special helper methods to implement things I found
        interesting:
        
        * ``datetime`` conversions for the start/completion timestamps,
        * ``url`` properties for representing the objects in Kojiweb,
        * Unified property attributes across task methods, like ``tag``, ``package`` or
          ``is_scratch``.
        
        More special return values:
        
        * ``getAverageBuildDuration`` returns a ``datetime.timedelta`` object instead
          of a raw float, because this is more useful to do time arithmetic.
        
        * The ``task_id`` property is populated on OSBS's CG container builds (a
          workaround for https://pagure.io/koji/issue/215).
        
        Message Parsing
        ---------------
        
        Koji's messagebus plugin emits messages to an AMQP broker when certain events
        happen. The ``txkoji.messages`` module has support for parsing these messages
        into the relevant txkoji ``Task`` or ``Build`` classes.
        
        
        TODO:
        =====
        * More KojiException subclasses for other possible XML-RPC faults?
        * Implement krbV authentication (probably not unless there is an alternative to
          python-krbV).
        * `MikeM noted
          <https://lists.fedorahosted.org/archives/list/koji-devel@lists.fedorahosted.org/message/ICFTEETD5MZMDY4S5FWFTO5LPKIAQIVW/>`_,
          the callnum parameter will need special handling. We might need Twisted's
          ``DeferredLock`` to ensure we only have one auth'd RPC in flight at a time.
          It's not really clear to me if we can actually hit a callnum error here. More
          integration testing needed for this.
        * Ensure that Brew's "build time" equals the longest "buildArch" time for a
          task, and not something else, like the buildSRPMFromSCM time, nor even the
          overall build task's time. This has implications for estimating scratch
          builds. (comparing our tasks' times to getAverageBuildDuration)
        
        Packages that use this package
        ==============================
        
        * `helga-koji <https://github.com/ktdreyer/helga-koji>`_
        
Keywords: koji,twisted
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Twisted
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.6
