chg: Updated api.py docstrings to comply with PEP257

pymisp/api.py

@@ -62,8 +62,7 @@ class analysis(object):
 
 
 class PyMISP(object):
-    """
+    """Python API for MISP
-        Python API for MISP
 
     :param url: URL of the MISP instance you want to connect to
     :param key: API key of the user you want to use
@@ -136,9 +135,8 @@ class PyMISP(object):
         self.sane_default = self.describe_types['sane_defaults']
 
     def __prepare_session(self, output='json'):
-        """
+        """Prepare the headers of the session"""
-            Prepare the headers of the session
+
-        """
         if not HAVE_REQUESTS:
             raise MissingDependency('Missing dependency, install requests (`pip install requests`)')
         session = requests.Session()
@@ -218,8 +216,7 @@ class PyMISP(object):
     # ################################################
 
     def get_index(self, filters=None):
-        """
+        """Return the index.
-            Return the index.
 
         Warning, there's a limit on the number of results
         """
@@ -233,8 +230,7 @@ class PyMISP(object):
         return self._check_response(response)
 
     def get_event(self, event_id):
-        """
+        """Get an event
-            Get an event
 
         :param event_id: Event id to get
         """
@@ -244,9 +240,7 @@ class PyMISP(object):
         return self._check_response(response)
 
     def get_stix_event(self, event_id=None, with_attachments=False, from_date=False, to_date=False, tags=False):
-        """
+        """Get an event/events in STIX format"""
-            Get an event/events in STIX format
-        """
         if tags:
             if isinstance(tags, list):
                 tags = "&&".join(tags)
@@ -260,8 +254,7 @@ class PyMISP(object):
         return self._check_response(response)
 
     def add_event(self, event):
-        """
+        """Add a new event
-            Add a new event
     
         :param event: Event as JSON object / string or XML to add
         """
@@ -274,8 +267,7 @@ class PyMISP(object):
         return self._check_response(response)
 
     def update_event(self, event_id, event):
-        """
+        """Update an event
-            Update an event
 
         :param event_id: Event id to update
         :param event: Event as JSON object / string or XML to add
@@ -289,8 +281,7 @@ class PyMISP(object):
         return self._check_response(response)
 
     def delete_event(self, event_id):
-        """
+        """Delete an event
-            Delete an event
 
         :param event_id: Event id to delete
         """
@@ -370,12 +361,10 @@ class PyMISP(object):
         return self._check_response(response)
 
     def _valid_uuid(self,uuid):
-        """
+        """Test if uuid is valid
-            Test if uuid is valid
+        Will test against CakeText's RFC 4122, i.e
-
+        "the third group must start with a 4,
-            CakeText::uuid follow RFC 4122
+        and the fourth group must start with 8, 9, a or b."
-             - the third group must start with a 4,
-             - the fourth group must start with 8, 9, a or b.
 
         :param uuid: an uuid
         """
@@ -739,8 +728,7 @@ class PyMISP(object):
     def search_index(self, published=None, eventid=None, tag=None, datefrom=None,
                      dateto=None, eventinfo=None, threatlevel=None, distribution=None,
                      analysis=None, attribute=None, org=None):
-        """
+        """Search only at the index level. Use ! infront of value as NOT, default OR
-            Search only at the index level. Use ! infront of value as NOT, default OR
 
         :param published: Published (0,1)
         :param eventid: Evend ID(s) | str or list
@@ -752,7 +740,6 @@ class PyMISP(object):
         :param distribution: Distribution level(s) (0,1,2,3) | str or list
         :param analysis: Analysis level(s) (0,1,2) | str or list
         :param org: Organisation(s) | str or list
-
         """
         allowed = {'published': published, 'eventid': eventid, 'tag': tag, 'Dateto': dateto,
                    'Datefrom': datefrom, 'eventinfo': eventinfo, 'threatlevel': threatlevel,
@@ -787,8 +774,7 @@ class PyMISP(object):
         return self.__query(session, 'restSearch/download', query)
 
     def __prepare_rest_search(self, values, not_values):
-        """
+        """Prepare a search, generate the chain processed by the server
-            Prepare a search, generate the chain processed by the server
 
         :param values: Values to search
         :param not_values: Values that should not be in the response
@@ -813,8 +799,7 @@ class PyMISP(object):
     def search(self, values=None, not_values=None, type_attribute=None,
                category=None, org=None, tags=None, not_tags=None, date_from=None,
                date_to=None, last=None, metadata=None, uuid=None, controller='events'):
-        """
+        """Search via the Rest API
-            Search via the Rest API
 
         :param values: values to search for
         :param not_values: values *not* to search for
@@ -865,12 +850,10 @@ class PyMISP(object):
         session = self.__prepare_session()
         return self.__query(session, 'restSearch/download', query, controller)
 
-    def get_attachement(self, event_id):
+    def get_attachment(self, event_id):
-        """
+        """Get attachement of an event (not sample)
-            Get attachement of an event (not sample)
 
-            :param event_id: Event id from where the attachements will
+        :param event_id: Event id from where the attachements will be fetched
-                             be fetched
         """
         attach = urljoin(self.root_url, 'attributes/downloadAttachment/download/{}'.format(event_id))
         session = self.__prepare_session()
@@ -918,8 +901,7 @@ class PyMISP(object):
         return True, details
 
     def download_last(self, last):
-        """
+        """Download the last updated events.
-            Download the last updated events.
 
         :param last: can be defined in days, hours, minutes (for example 5d or 12h or 30m)
         """
@@ -928,17 +910,14 @@ class PyMISP(object):
     # ############## Suricata ###############
 
     def download_all_suricata(self):
-        """
+        """Download all suricata rules events."""
-            Download all suricata rules events.
-        """
         suricata_rules = urljoin(self.root_url, 'events/nids/suricata/download')
         session = self.__prepare_session('rules')
         response = session.get(suricata_rules)
         return response
 
     def download_suricata_rule_event(self, event_id):
-        """
+        """Download one suricata rule event.
-            Download one suricata rule event.
 
         :param event_id: ID of the event to download (same as get)
         """
@@ -972,15 +951,11 @@ class PyMISP(object):
     # ########## Version ##########
 
     def get_api_version(self):
-        """
+        """Returns the current version of PyMISP installed on the system"""
-            Returns the current version of PyMISP installed on the system
-        """
         return {'version': __version__}
 
     def get_api_version_master(self):
-        """
+        """Get the most recent version of PyMISP from github"""
-            Get the most recent version of PyMISP from github
-        """
         r = requests.get('https://raw.githubusercontent.com/MISP/PyMISP/master/pymisp/__init__.py')
         if r.status_code == 200:
             version = re.findall("__version__ = '(.*)'", r.text)
@@ -989,18 +964,14 @@ class PyMISP(object):
             return {'error': 'Impossible to retrieve the version of the master branch.'}
 
     def get_version(self):
-        """
+        """Returns the version of the instance."""
-            Returns the version of the instance.
-        """
         session = self.__prepare_session()
         url = urljoin(self.root_url, 'servers/getVersion.json')
         response = session.get(url)
         return self._check_response(response)
 
     def get_version_master(self):
-        """
+        """Get the most recent version from github"""
-            Get the most recent version from github
-        """
         r = requests.get('https://raw.githubusercontent.com/MISP/MISP/2.4/VERSION.json')
         if r.status_code == 200:
             master_version = json.loads(r.text)
@@ -1020,9 +991,7 @@ class PyMISP(object):
     # ############## Statistics ##################
 
     def get_attributes_statistics(self, context='type', percentage=None):
-        """
+        """Get attributes statistics from the MISP instance"""
-            Get attributes statistics from the MISP instance
-        """
         session = self.__prepare_session()
         if (context != 'category'):
             context = 'type'
@@ -1034,9 +1003,7 @@ class PyMISP(object):
         return self._check_response(response)
 
     def get_tags_statistics(self, percentage=None, name_sort=None):
-        """
+        """Get tags statistics from the MISP instance"""
-        Get tags statistics from the MISP instance
-        """
         session = self.__prepare_session()
         if percentage is not None:
             percentage = 'true'