NailGun

NailGun is a GPL-licensed Python library that facilitates easy usage of the Satellite 6 API. It lets you write code like this:

>>> org = Organization(id=1).read()

This page provides a summary of information about NailGun.

More in-depth coverage is provided in other sections.

Quick Start

This script demonstrates how to create and delete an organization, and how to save some of our work for later re-use:

>>> from nailgun.config import ServerConfig
>>> from nailgun.entities import Organization
>>> server_config = ServerConfig(
...     auth=('admin', 'changeme'),      # Use these credentials…
...     url='https://sat1.example.com',  # …to talk to this server.
... )  # More options are available, e.g. disabling SSL verification.
>>> org = Organization(server_config, name='junk org').create()
>>> org.name == 'junk org'  # Access all attrs likewise, e.g. `org.label`
True
>>> org.delete()
>>> server_config.save()  # Save to disk w/label 'default'. Read with get()

This example glosses over many features. The Examples and API documentation sections provide more in-depth documentation.

Why NailGun?

NailGun exists to make working with the Satellite 6 API easier. Here are some of the challenges developers face:

  • Existing libraries, such as the Python Requests library, are general purpose tools. As a result, client code can easily become excessively verbose. See the Examples document for an example.
  • The Satellite 6 API is not RESTful in its design. As a result, even experienced developers may find the API hard to work with.
  • The Satellite 6 API is not consistent in its implementation. For example, see the “Payload Generation” section of this blog post.

All of the above issues are compounded by the size of the Satellite 6 API. As of this writing, there are 405 paths. This makes it tough to design compact and elegant client code.

NailGun addresses these issues. NailGun is specialized, it has a consistent design, it abstracts away many painful implementation details and it contains workarounds for certain bugs. Why use a hammer when you can use a nail gun?

Scope and Limitations

NailGun is not an officially supported product. NailGun is a Python-only library, and integration with other languages such as Java or Ruby is not currently a consideration. Although NailGun is developed with a broad audience in mind, it targets Robottelo first and foremost.

NailGun was originally conceived as a set of helper routines internal to Robottelo. It has since been extracted from that code base and turned in to an independently useful library.

Warning

Until version 1.0 is released, functionality will be incomplete, and breaking changes may be introduced. Users are advised to read the release notes closely.

Resources

The Examples and API documentation sections provide more in-depth documentation.

Join the #robottelo channel on the freenode IRC network to chat with a human. The Robottelo source code contains many real-world examples how NailGun is used, especially the tests/foreman/api/ directory. This blog post provides a glimpse in to the challenges that NailGun is designed to overcome.

Contributing

Contributions are encouraged. The easiest way to contribute is to submit a pull request on GitHub, but patches are welcome no matter how they arrive.

You can use pip and make to quickly set up a development environment:

pip install -r requirements.txt -r requirements-dev.txt
make lint
make test
make docs-html

Please adhere to the following guidelines:

  • Lint your code with flake8 and pylint. This can be done easily by executing make lint. The former linter must pass with zero warnings, and warnings from the latter linter should be minimized.

  • Check for errors by running the unit test suite. This can be done easily by executing make test. It must pass with zero errors.

  • Document your code. Documentation can be easily generated by executing make docs-html.

  • Unit tests are very highly recommended.

  • Adhere to typical commit guidelines:

    • Commits should not cause NailGun to break.
    • Commits should be small and coherent. One commit should address one issue.
    • Commits should have good commit messages.
    • Rebasing is encouraged. Rebasing produces a much nicer commit history than merging.
  • When in doubt, ask on IRC.