Merge pull request #31 from rbw0/branch0.4.2

Version 0.4.2
rbw · Apr 17, 2017 · b636a3d · b636a3d
2 parents c19d794 + 94962a2
commit b636a3d
Show file tree

Hide file tree

Showing 16 changed files with 113 additions and 58 deletions.
diff --git a/README.rst b/README.rst
@@ -1,46 +1,48 @@
-::
+.. code-block::
   
 	 ______   __  __    ______    __   __    ______    __     __    
 	/\  == \ /\ \_\ \  /\  ___\  /\ "-.\ \  /\  __ \  /\ \  _ \ \   
 	\ \  _-/ \ \____ \ \ \___  \ \ \ \-.  \ \ \ \/\ \ \ \ \/ ".\ \  
 	 \ \_\    \/\_____\ \/\_____\ \ \_\\"\_\ \ \_____\ \ \__/".~\_\ 
 	  \/_/     \/_____/  \/_____/  \/_/ \/_/  \/_____/  \/_/   \/_/ 
 			- a Python library for the ServiceNow REST API
-
+			
 .. image:: https://travis-ci.org/rbw0/pysnow.svg?branch=master
     :target: https://travis-ci.org/rbw0/pysnow
 .. image:: https://coveralls.io/repos/github/rbw0/pysnow/badge.svg?branch=master
-	:target: https://coveralls.io/github/rbw0/pysnow?branch=master
-
+    :target: https://coveralls.io/github/rbw0/pysnow?branch=master
+.. image:: https://badge.fury.io/py/pysnow.svg
+    :target: https://pypi.python.org/pypi/pysnow
+
 Installation
-^^^^^^^^^^^^
+------------
 # pip install pysnow
 
 
 Usage examples
-^^^^^^^^^^^^^^
+--------------
 Go `here <http://pysnow.readthedocs.io/en/latest/usage>`_ for usage examples
 
 
 Documentation
-^^^^^^^^^^^^^
+-------------
 The full documentation is available `here <http://pysnow.readthedocs.org/>`_
 
 
 Compatibility
-^^^^^^^^^^^^^
+-------------
 Python 2 and 3. Tested: Python 2.6+ and Python 3.3+
 
 Contributors
-^^^^^^^^^^^^
+------------
 lingfish, jcpunk, AMMullan, amontalban, ryancurrah, jdugan1024
 
 
 JetBrains
-^^^^^^^^^
+---------
 Thank you Jetbrains (www.jetbrains.com) for supporting with IDE licenses!
 
 Author
-^^^^^^
+------
 Created by Robert Wikman <[email protected]> in 2016
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -10,11 +10,14 @@ Python library for the ServiceNow REST API
 .. toctree::
    :maxdepth: 1
 
-   client
-   query
    request
-   usage/index
+   query
+   client
+
 
+Usage
+-----
+Go  `here <usage>`_ for usage examples.
 
 Installation
 ------------
@@ -23,7 +26,7 @@ Installation
 Limitations
 -----------
 Currently `delete()` and `update()` operations only works for queries yielding a single result.
-If there's a demand, delete_multiple() and update_multiple() will be implemented into the API to avoid accidents.
+If there's a demand, this support will be implemented into the API along with `force_multiple` to avoid accidents.
 
 Compatibility
 -------------

diff --git a/docs/request.rst b/docs/request.rst
@@ -4,4 +4,5 @@
 .. automodule:: pysnow
 .. autoclass:: Request
     :members:
+.. autoexception:: pysnow.exceptions.UnexpectedResponse
 
diff --git a/docs/usage/full/clone.rst b/docs/usage/full/clone.rst
@@ -1,7 +1,7 @@
 Cloning
 -------
 
-Check out the :meth:`clone() documentation <pysnow.Request.clone>` for more info
+See the :meth:`pysnow.Request.clone` documentation for more details.
 
 
 .. code-block:: python

diff --git a/docs/usage/full/create.rst b/docs/usage/full/create.rst
@@ -1,7 +1,7 @@
 Creating a new record
 ---------------------
 
-Check out the :meth:`insert() documentation <pysnow.Request.insert>` for more info
+See the :meth:`pysnow.Request.insert` documentation for more details.
 
 .. code-block:: python
 

diff --git a/docs/usage/full/delete.rst b/docs/usage/full/delete.rst
@@ -0,0 +1,18 @@
+Deleting a record
+-----------------
+
+See the :meth:`pysnow.Request.delete` documentation for more details.
+
+.. code-block:: python
+
+   import pysnow
+
+   # Create client object
+   s = pysnow.Client(instance='myinstance', user='myusername', password='mypassword')
+
+   # Delete record with number 'INC012345'
+   res = s.query(table='incident', query={'number': 'INC012345'}).delete()
+
+   # Print out the result
+   print(res)
+
diff --git a/docs/usage/full/get_all.rst b/docs/usage/full/get_all.rst
@@ -1,30 +1,19 @@
-Getting multiple records using the query builder
-------------------------------------------------
+Getting multiple records
+------------------------
 
-Check out the :meth:`get_all() documentation <pysnow.Request.get_all>` for more info
+See the :meth:`pysnow.Request.get_all` documentation for more details.
 
 .. code-block:: python
 
    import pysnow
-   from datetime import datetime as dt
-   from datetime import timedelta as td
 
    # Create client object
    s = pysnow.Client(instance='myinstance', user='myusername', password='mypassword')
 
-   # Set start and end range
-   start = dt(1970, 1, 1)
-   end = dt.now() - td(days=20)
+   # Get all incidents
+   r = s.query('incident', query={})
 
-   # Query incident records with number starting with 'INC0123', created between 1970-01-01 and 20 days back in time
-   qb = pysnow.QueryBuilder()\
-     .field('number').starts_with('INC0123')\
-     .AND()\
-     .field('sys_created_on').between(start, end)
-
-   r = s.query('incident', query=qb)
-
-   # Iterate over the result and print out number
-   for record in r.get_all():
+   # Set the limit of records returned from server to 20, then iterate over the result and print out number
+   for record in r.get_all(limit=20):
        print(record['number'])
 
diff --git a/docs/usage/full/get_one.rst b/docs/usage/full/get_one.rst
@@ -1,7 +1,7 @@
 Getting a single record
 -----------------------
 
-Check out the :meth:`get_one() documentation <pysnow.Request.get_one>` for more info
+See the :meth:`pysnow.Request.get_one` documentation for more details.
 
 .. code-block:: python
 

diff --git a/docs/usage/full/query_builder.rst b/docs/usage/full/query_builder.rst
@@ -0,0 +1,30 @@
+Using the query builder
+-----------------------
+
+See the :meth:`pysnow.Request.get_all` and :meth:`pysnow.QueryBuilder` documentation for more details.
+
+.. code-block:: python
+
+   import pysnow
+   from datetime import datetime as dt
+   from datetime import timedelta as td
+
+   # Create client object
+   s = pysnow.Client(instance='myinstance', user='myusername', password='mypassword')
+
+   # Set start and end range
+   start = dt(1970, 1, 1)
+   end = dt.now() - td(days=20)
+
+   # Query incident records with number starting with 'INC0123', created between 1970-01-01 and 20 days back in time
+   qb = pysnow.QueryBuilder()\
+     .field('number').starts_with('INC0123')\
+     .AND()\
+     .field('sys_created_on').between(start, end)
+
+   r = s.query('incident', query=qb)
+
+   # Iterate over the result and print out number
+   for record in r.get_all():
+       print(record['number'])
+
diff --git a/docs/usage/full/update.rst b/docs/usage/full/update.rst
@@ -1,7 +1,7 @@
 Updating a record
 -----------------
 
-Check out the :meth:`update() documentation <pysnow.Request.update>` for more info
+See the :meth:`pysnow.Request.update` documentation for more details.
 
 .. code-block:: python
 

diff --git a/docs/usage/index.rst b/docs/usage/index.rst
@@ -1,20 +1,20 @@
-Usage examples
-==============
+Usage
+^^^^^
 
 .. toctree::
-   :caption: Usage
-
    client
    query
    request
 
 .. toctree::
    :maxdepth: 1
-   :caption: Full usage examples
+   :caption: Full examples
 
    full/get_one
    full/get_all
    full/create
+   full/query_builder
    full/update
+   full/delete
    full/clone
 
diff --git a/docs/usage/query.rst b/docs/usage/query.rst
@@ -3,7 +3,6 @@ Creating a query
 
 Although optional, querying a good way to specify what you're after.
 
-Pysnow offers multiple ways to query the ServiceNow REST API.
 
 Using key-value
 ^^^^^^^^^^^^^^^
@@ -18,7 +17,8 @@ Using the query builder
 ^^^^^^^^^^^^^^^^^^^^^^^
 Perhaps a bit verbose, but pretty simple and powerful.
 
-See the :meth:`QueryBuilder documentation <pysnow.QueryBuilder>` for more info
+See the :meth:`pysnow.QueryBuilder` documentation for more details.
+
 
 .. code-block:: python
 

diff --git a/docs/usage/request.rst b/docs/usage/request.rst
@@ -6,6 +6,8 @@ See the :meth:`Request documentation <pysnow.Request>` for more info
 Creating a new record
 ---------------------
 
+See the :meth:`pysnow.Request.insert` documentation for more details.
+
 .. code-block:: python
 
     # Create a new record
@@ -18,7 +20,9 @@ Creating a new record
 Getting a single record
 ------------------------
 
-Here we'll utilize `get_one()`, a convenience function for getting a single record without having to use a generator.
+Here we'll utilize get_one(), a convenience function for getting a single record without having to use a generator.
+
+See the :meth:`pysnow.Request.get_one` documentation for more details.
 
 .. code-block:: python
 
@@ -32,7 +36,9 @@ Here we'll utilize `get_one()`, a convenience function for getting a single reco
 Getting multiple records
 ------------------------
 
-`get_all()` returns a generator response (iterable) , also, this method chains linked responses
+get_all() returns a generator response (iterable) , also, this method chains linked responses.
+
+See the :meth:`pysnow.Request.get_all` documentation for more details.
 
 .. code-block:: python
 
@@ -47,6 +53,8 @@ Getting multiple records
 Updating a record
 -----------------
 
+See the :meth:`pysnow.Request.update` documentation for more details.
+
 .. code-block:: python
 
     request = s.query(table='incident', query={'number': 'INC01234'})
@@ -61,6 +69,8 @@ Updating a record
 Deleting a record
 ---------------------
 
+See the :meth:`pysnow.Request.delete` documentation for more details.
+
 .. code-block:: python
 
     # Query the incident table by number
@@ -77,6 +87,8 @@ Deleting a record
 Request error handling
 ----------------------
 
+See the :meth:`pysnow.exceptions.UnexpectedResponse` documentation for more details.
+
 `UnexpectedResponse` can be used with all CRUD methods and contains important information of what went wrong when interfacing with the API
 
 .. code-block:: python

diff --git a/pysnow/__init__.py b/pysnow/__init__.py
@@ -6,4 +6,4 @@
 from pysnow.exceptions import *
 
 __author__ = "Robert Wikman <[email protected]>"
-__version__ = "0.4.1"
+__version__ = "0.4.2"
diff --git a/pysnow/client.py b/pysnow/client.py
@@ -62,15 +62,15 @@ def _request(self, method, table, **kwargs):
         :return: `Request` object
         """
         return request.Request(method,
-                       table,
-                       default_payload=self.default_payload,
-                       raise_on_empty=self.raise_on_empty,
-                       session=self.session,
-                       instance=self.instance,
-                       **kwargs)
+                               table,
+                               default_payload=self.default_payload,
+                               raise_on_empty=self.raise_on_empty,
+                               session=self.session,
+                               instance=self.instance,
+                               **kwargs)
 
     def query(self, table, **kwargs):
-        """Query wrapper method.
+        """Query (GET) request wrapper.
 
         :param table: table to perform query on
         :param kwargs: Keyword arguments passed along to `Request`
@@ -79,7 +79,7 @@ def query(self, table, **kwargs):
         return self._request('GET', table, **kwargs)
 
     def insert(self, table, payload, **kwargs):
-        """Creates a new `Request` object and calls insert()
+        """Insert (POST) request wrapper
 
         :param table: table to insert on
         :param payload: update payload (dict)

diff --git a/pysnow/query.py b/pysnow/query.py
@@ -17,15 +17,15 @@ def __init__(self):
         self.l_oper = None
 
     def AND(self):
-        """Operator for use between expressions"""
+        """And operator"""
         return self._add_logical_operator('^')
 
     def OR(self):
-        """Operator for use between expressions"""
+        """OR operator"""
         return self._add_logical_operator('^OR')
 
     def NQ(self):
-        """Operator for use between expressions"""
+        """NQ (new query) operator"""
         return self._add_logical_operator('^NQ')
 
     def field(self, field):