=============================
hub-client
=============================

.. image:: https://badge.fury.io/py/hub-client.png
    :target: https://badge.fury.io/py/hub-client

.. image:: https://travis-ci.org/docker/hub-client.png?branch=master
    :target: https://travis-ci.org/docker/hub-client

.. image:: https://coveralls.io/repos/docker/hub-client/badge.png?branch=master
    :target: https://coveralls.io/r/docker/hub-client?branch=master

Python client for docker hub

Documentation
-------------

Release Instructions
====================

1. create a virtualenv
2. install the dev requirements `pip install -r requirements-dev.txt`
3. Make sure you have "Write Access" to the hub-client repository.
4. run `./publish.py {major|minor|patch}`

Quickstart
----------

Install hub-client::

    pip install hub-client

Then use it in a project::

    import dockerhub


Unit Testing
------------

Run the following for unit tests::

    python ./run-unittests.py


Run the following for integration tests::

    python ./run-integration-tests.py


Run the following for coverage::

    coverage run run-unittests.py && coverage html --include=`pwd`"/*"


Features
--------

- DockerJsonFormatter

Implements the standard Docker JSON format and parsed by our centralized logging infrastructure.

The 'service', 'version' and 'environment' are added to every log
message and are expected by our centralized logging parsers. The format
is used for services like Registry and Garant as well.

The current implementation is tied to Django but it should be easy
to modify to handle any python logging.

How to configure Django to use the logger::

    VERSION_NUMBER = "1.75.1"
    SERVICE_NAME = 'hub-reghub'
    RELEASE_STAGE = 'development'

    LOGGING = {
        'version': 1,
        'disable_existing_loggers': False,
        'formatters': {
            'json': {
                '()': 'common.logger.DockerJsonFormatter',
                # this strings define as values are outputted to the log
                'format': '%(levelname)s %(asctime)s %(name)s %(pathname)s %(filename)s %(module)s %(lineno)d %(message)s %(exc_info)s'
            },
        },
        'handlers': {
            'console': {
                'level': 'DEBUG',
                'class': 'logging.StreamHandler',
                'formatter': default_console_formatter
            },
        },
        'loggers': {
            'django.request': {
                'handlers': ['file'],
                'level': 'DEBUG',
                'propagate': True,
            },
        },
    }

- BugsnagHandler

Implements a bugsnag handler and logger patching that allows us to integrate
with Bugsnag using the standard python logging methods.

How to configure django to use the logger:

1) Patch the logger. Do this in the __init__.py of the code. This will execute
   the patching at runtime.  Don't do this in the settings, you'll encounter
   strange import problems::

       # ex: https://github.com/docker/docker-io/blob/HUB-557/docker_io/common/__init__.py#L7
       from dockerhub.logger import patch_logging_logger
       patch_logging_logger()

2) Add the bugsnag handler to the django LOGGER section::
   
      'handlers': {
         'bugsnag': {
            'level': 'WARNING',
            'class': 'dockerhub.logger.BugsnagHandler',
         },
      },

3) If the log record has a 'extra' attribute, it'll be handled specially:
    - If extra is not a dictionary, it's ignored.
    - If extra has a 'context' key, that value is set as the bugsnag context.
    - Other key/value pairs in extra will show up under a "custom data" tab.

    Note that our logging.Logger is patched to retain 'extra'.
    So here's an example:

        LOG.error("Godzilla attack!",
                  extra={'city': 'SF',
                         'damage': 'GG Bridge destroyed',
                         'context': 'Disaster!',
                         'year': '2015'})

        The bugsnag context will show 'Disaster!'.

        In the "custom data" tab in bugsnag, you'll see:
           * city: SF
           * damage: GG Bridge destroyed
           * year: 2015

* TODO (Document features)