From a2d20806d45a5003ccf59365053af8e4ba354cd0 Mon Sep 17 00:00:00 2001 From: Jeremy Audet Date: Mon, 22 Jun 2015 17:23:36 -0400 Subject: [PATCH] Update "examples" section in documentation * Add table of contents where appropriate. * Place the video introduction in to its own section. * Explain how it is possible to call `create()`, `read()`, etc on both brand new and existing objects. --- docs/examples.rst | 93 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 73 insertions(+), 20 deletions(-) diff --git a/docs/examples.rst b/docs/examples.rst index d9c9bb46..44b0df4c 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -4,15 +4,15 @@ Examples This page contains several examples of how to use NailGun. The examples progress from simple to more advanced. -You can run any of the scripts presented in this document. For example scripts -that use NailGun, this is the set-up procedure:: +You can run any of the scripts presented in this document. This is the set-up +procedure for scripts that use NailGun:: virtualenv env source env/bin/activate pip install nailgun ./some_script.py # some script of your choice -For example scripts that do not use NailGun, this is the set-up procedure:: +This is the set-up procedure for scripts that do not use NailGun:: virtualenv env source env/bin/activate @@ -22,6 +22,14 @@ For example scripts that do not use NailGun, this is the set-up procedure:: Additionally, a video demonstration entitled `NailGun Hands On `_ is available. +.. contents:: + +Video Demonstration +------------------- + +Note that this video does not touch on features that were added after it was +recorded on May 26 2015, such as the :ref:`label-update` method. + .. raw:: html -.. _label-simple: +.. _label-getting-started: Getting Started --------------- @@ -88,7 +96,7 @@ configurations, but only want to work with one at a time:: In addition, if no server configuration object is specified when instantiating an :class:`nailgun.entity_mixins.Entity` object, the server configuration labeled "default" is used. With this in mind, here's a revised version of the -first script in section :ref:`label-simple`: +first script in section :ref:`label-getting-started`: .. literalinclude:: create_organization_nailgun_v2.py @@ -113,19 +121,18 @@ The examples so far have only made use of a small set of classes and methods: methods. However, there are several more very useful high-level methods that you should -be aware of: - -* ``get_fields`` -* ``read`` -* ``update`` +be aware of. In addition, there are aspects to the ``create`` method that have +not been touched on. +.. contents:: + :local: ``get_fields`` ~~~~~~~~~~~~~~ The ``get_fields`` method is closely related to the ``get_values`` method. The former tells you which values *may* be assigned to an entity, and the latter -tells you what values *are* assigned to an entity. For example: +tells you what values *are* assigned to an entity. For example:: >>> from nailgun.entities import Product >>> product = Product(name='junk product') @@ -174,14 +181,32 @@ Secondly, fields can generate random values for unit testing purposes. (This does *not* normally happen!) See the ``create_missing`` method for more information. +``create`` +~~~~~~~~~~ + +So far, we have only used brand new objects:: + + >>> from nailgun.entities import Organization + >>> org = entities.Organization(name='junk org').create() + +However, we can also use existing objects:: + + >>> from nailgun.entities import Organization + >>> org = entities.Organization() + >>> org.name = 'junk org' + >>> org = org.create() + +Note that the ``create`` method is side-effect free. As a result, the ``org = +org.create()`` idiom is advisable. (The next section discusses this more.) + ``read`` ~~~~~~~~ -Rather unsurprisingly, the ``read`` method fetches information about an entity. -Importantly, the ``read`` method does not have side-effects: +The ``read`` method fetches information about an entity. Typical usages of this +method have already been shown, so this example goes in to more detail:: - >>> from nailgun import entities - >>> org = entities.Organization(id=418) + >>> from nailgun.entities import Organization + >>> org = Organization(id=418) >>> response = org.read() >>> for obj in (org, response): ... type(obj) @@ -200,15 +225,33 @@ Importantly, the ``read`` method does not have side-effects: 'title': 'junk org', } -As demonstrated above, the ``read`` method does not alter the object it is -called on. Instead, it creates a new object, populates that object with -attributes, and returns that new object. As a result, idioms like ``org = -org.read()`` are advisable. +Some notes on the above: + +* The ``read`` method requires that an ``id`` attribute be present. Running + ``Organization().read()`` will throw an exception. +* The ``read`` method is side-effect free. Rather than altering the object it is + called on, it creates a new object, populates that object with attributes and + returns the object. As a result, idioms like ``org = org.read()`` are + advisable. + +So far, we have only used brand new objects:: + + >>> from nailgun.entities import Organization + >>> org = Organization(id=418).read() + +However, we can also use existing objects:: + + >>> from nailgun.entities import Organization + >>> org = Organziation() + >>> org.id = 418 + >>> org = org.read() + +.. _label-update: ``update`` ~~~~~~~~~~ -The ``update`` method updates an entity's values. For example: +The ``update`` method updates an entity's values. For example:: >>> from nailgun.entities import Organization >>> org = Organization(id=418).read() @@ -249,6 +292,16 @@ Some notes on the above: * The ``update`` method is side-effect free. As a result, idioms like ``org = org.update()`` are advisable. +So far, we have only called ``update`` on existing objects. However, we can also +call ``update`` on brand new objects:: + + >>> from nailgun.entities import Organization + >>> Organization( + ... id=418, + ... name='junkier org', + ... description='supercalifragilisticexpialidocious', + ... ).update(['name', 'description']) + Using Lower Layers ------------------