<commit_before>Usage examples
==============

Import and instantiation
------------------------

.. code-block:: python

    import pysnow

    # Create client object
    s = pysnow.Client(instance='myinstance',
                      user='myusername',
                      password='<PASSWORD>',
                      raise_on_empty=True)


Getting a single record
------------------------

Here we'll utilize `get_one()`, a convenience function for getting a single record without having to use a generator.

.. code-block:: python

    request = s.query(table='incident', query={'number': 'INC01234'})

    # Fetch one record and filter out everything but 'number' and 'sys_id' from the results
    result = request.get_one(fields=['number', 'sys_id'])
    print(result['number'])


Getting all records
-------------------

`get_all()` returns a generator response (iterable) , also, this method chains linked responses

.. code-block:: python

    request = s.query(table='incident', query={'state': 2})

    # Fetch all records without using a field filter,
    # then iterate over the results and print out sys_ids
    while record in request.get_all():
        print(record['sys_id'])


Updating a record
-----------------

.. code-block:: python

    request = s.query(table='incident', query={'number': 'INC01234'})

    # Update the record
    result = request.update({'description': 'test'})

    print("Record '%s' was successfully updated" % result)


Creating a new record
---------------------

.. code-block:: python

    # Create a new record
    result = s.insert(table='incident', payload={'field1': 'value1', 'field2': 'value2'})

    # Print out the number of the created record
    print(result['number'])


Deleting a record
---------------------

.. code-block:: python

    # Query the incident table by number
    request = s.query(table='incident', query={'number': 'INC01234'})

    # Delete the record
    result = request.delete()

    if result['success'] == True:
        print("Record deleted")

<commit_msg>Added error handling<commit_after>Usage examples
==============

Import and instantiation
------------------------

.. code-block:: python

    import pysnow

    # Create client object
    s = pysnow.Client(instance='myinstance',
                      user='myusername',
                      password='<PASSWORD>',
                      raise_on_empty=True)


Getting a single record
------------------------

Here we'll utilize `get_one()`, a convenience function for getting a single record without having to use a generator.

.. code-block:: python

    request = s.query(table='incident', query={'number': 'INC01234'})

    # Fetch one record and filter out everything but 'number' and 'sys_id' from the results
    result = request.get_one(fields=['number', 'sys_id'])
    print(result['number'])


Getting all records
-------------------

`get_all()` returns a generator response (iterable) , also, this method chains linked responses

.. code-block:: python

    request = s.query(table='incident', query={'state': 2})

    # Fetch all records without using a field filter,
    # then iterate over the results and print out sys_ids
    while record in request.get_all():
        print(record['sys_id'])


Updating a record
-----------------

.. code-block:: python

    request = s.query(table='incident', query={'number': 'INC01234'})

    # Update the record
    result = request.update({'description': 'test'})

    print("Record '%s' was successfully updated" % result)


Creating a new record
---------------------

.. code-block:: python

    # Create a new record
    result = s.insert(table='incident', payload={'field1': 'value1', 'field2': 'value2'})

    # Print out the number of the created record
    print(result['number'])


Deleting a record
---------------------

.. code-block:: python

    # Query the incident table by number
    request = s.query(table='incident', query={'number': 'INC01234'})

    # Delete the record
    result = request.delete()

    if result['success'] == True:
        print("Record deleted")



Catching server response errors
-------------------------------

`UnexpectedResponse` can be used with all CRUD methods and contains important information of what went wrong when interfacing with the API

.. code-block:: python

   # Create new record and catch possible server response exceptions
   try:
       s.insert(table='incident', payload={'field1': 'value1', 'field2': 'value2'})
   except pysnow.UnexpectedResponse as e:
       print("%s, details: %s" % (e.error_summary, e.error_details))


{'fraction_non_alphanumeric': 0.17910772578890097, 'fraction_numerical': 0.009575625680087052, 'mean_word_length': 2.5878220140515222, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3466076', 'n_tokens_mistral': 1285, 'n_tokens_neox': 1207, 'n_words': 407}