diff --git a/README.rst b/README.rst index 076637b..febf40e 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,4 @@ -:: +.. code-block:: ______ __ __ ______ __ __ ______ __ __ /\ == \ /\ \_\ \ /\ ___\ /\ "-.\ \ /\ __ \ /\ \ _ \ \ @@ -6,41 +6,43 @@ \ \_\ \/\_____\ \/\_____\ \ \_\\"\_\ \ \_____\ \ \__/".~\_\ \/_/ \/_____/ \/_____/ \/_/ \/_/ \/_____/ \/_/ \/_/ - 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 `_ for usage examples Documentation -^^^^^^^^^^^^^ +------------- The full documentation is available `here `_ 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 in 2016 diff --git a/docs/index.rst b/docs/index.rst index e944ee2..a9266d2 100644 --- 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 `_ 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 index 34e142b..54dd8a8 100644 --- 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 index 081ee9d..b7f9f03 100644 --- a/docs/usage/full/clone.rst +++ b/docs/usage/full/clone.rst @@ -1,7 +1,7 @@ Cloning ------- -Check out the :meth:`clone() documentation ` 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 index c406f6d..437cc7a 100644 --- 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 ` 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 new file mode 100644 index 0000000..635a9b1 --- /dev/null +++ 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 index 4ee9789..caeecbc 100644 --- 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 ` 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 index d084c54..8edec29 100644 --- 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 ` 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 new file mode 100644 index 0000000..572e348 --- /dev/null +++ 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 index 7ca7e7a..befcc4d 100644 --- 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 ` 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 index a80fb99..d73969b 100644 --- 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 index b81c107..857f2d1 100644 --- 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 ` 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 index c9fdef8..ac90797 100644 --- a/docs/usage/request.rst +++ b/docs/usage/request.rst @@ -6,6 +6,8 @@ See the :meth:`Request documentation ` 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 index 9be0425..dfc764f 100644 --- a/pysnow/__init__.py +++ b/pysnow/__init__.py @@ -6,4 +6,4 @@ from pysnow.exceptions import * __author__ = "Robert Wikman " -__version__ = "0.4.1" +__version__ = "0.4.2" diff --git a/pysnow/client.py b/pysnow/client.py index 3097335..3c54fd8 100644 --- 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 index e88da0a..dfa5020 100644 --- 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):