Merge pull request #73 from intezer/feature/docs

Feature/docs

CHANGES

@@ -1,4 +1,4 @@
-Unreleased
+1.14.4
 -------
 - Add analysis time to analysis object
 

intezer_sdk/__init__.py

@@ -1 +1 @@
-__version__ = '1.14.3'
+__version__ = '1.14.4'

intezer_sdk/analysis.py

@@ -23,6 +23,10 @@
 
 
 class FileAnalysis(BaseAnalysis):
+    """
+    FileAnalysis is a class for analyzing files. It is a subclass of the BaseAnalysis class and requires an API connection to Intezer.
+    """
+
     def __init__(self,
                  file_path: str = None,
                  file_hash: str = None,
@@ -35,6 +39,21 @@ def __init__(self,
                  zip_password: str = None,
                  download_url: str = None,
                  sandbox_command_line_arguments: str = None):
+        """
+        FileAnalysis is a class for analyzing files. It is a subclass of the BaseAnalysis class and requires an API connection to Intezer.
+
+        :param file_path: The file path of the file to be analyzed.
+        :param file_hash: The hash of the file to be analyzed.
+        :param file_stream: A binary stream of the file to be analyzed.
+        :param disable_dynamic_unpacking: A flag to disable dynamic unpacking during analysis.
+        :param disable_static_unpacking: A flag to disable static unpacking during analysis.
+        :param api: The API connection to Intezer.
+        :param file_name: The name of the file.
+        :param code_item_type: The type of the file, either "file" or "memory module".
+        :param zip_password: The password for a password-protected zip file.
+        :param download_url: A URL from which to download the file to be analyzed.
+        :param sandbox_command_line_arguments: The command line arguments for sandbox analysis.
+        """
         super().__init__(api)
         if [file_path, file_hash, file_stream, download_url].count(None) < 3:
             raise ValueError('Choose between file hash, file stream, file path, or download from url analysis')
@@ -75,6 +94,13 @@ def __init__(self,
 
     @classmethod
     def from_analysis_id(cls, analysis_id: str, api: IntezerApi = None) -> Optional['FileAnalysis']:
+        """
+        Returns a FileAnalysis instance with the given analysis ID.
+        Returns None when analysis doesn't exist.
+       :param analysis_id: The ID of the analysis to retrieve.
+       :param api: The API connection to Intezer.
+       :return: A FileAnalysis instance with the given analysis ID.
+        """
         api = api or get_global_api()
         response = api.get_file_analysis_response(analysis_id, True)
         return cls._create_analysis_from_response(response, api, analysis_id)
@@ -85,6 +111,15 @@ def from_latest_hash_analysis(cls,
                                   api: IntezerApi = None,
                                   private_only: bool = False,
                                   **additional_parameters) -> Optional['FileAnalysis']:
+        """
+        Returns the latest FileAnalysis instance for the given file hash, with the option to filter by private analyses only.
+        Returns None when analysis doesn't exist.
+        :param file_hash: The hash of the file to retrieve analysis for.
+        :param api: The API connection to Intezer.
+        :param private_only: A flag to filter results by private analyses only.
+        :param additional_parameters: Additional parameters to pass to the API.
+        :return: The latest FileAnalysis instance for the given file hash.
+        """
         api = api or get_global_api()
         analysis_report = api.get_latest_analysis(file_hash, private_only, **additional_parameters)
 

intezer_sdk/api.py

@@ -466,9 +466,9 @@ def get_index_response(self, index_id: str) -> Response:
 
         return response
 
-    def _set_access_token(self, api_key: str):
+    def _set_access_token(self):
         response = requests.post(self.full_url + '/get-access-token',
-                                 json={'api_key': api_key},
+                                 json={'api_key': self.api_key},
                                  verify=self._verify_ssl)
 
         if response.status_code in (HTTPStatus.UNAUTHORIZED, HTTPStatus.BAD_REQUEST):
@@ -482,7 +482,7 @@ def set_session(self):
         self._session = requests.session()
         self._session.mount('https://', requests.adapters.HTTPAdapter(max_retries=3))
         self._session.verify = self._verify_ssl
-        self._set_access_token(self.api_key)
+        self._set_access_token()
         self._session.headers['Authorization'] = 'Bearer {}'.format(self._access_token)
         self._session.headers['User-Agent'] = self.user_agent
 

intezer_sdk/base_analysis.py

@@ -16,7 +16,14 @@
 
 
 class Analysis(metaclass=abc.ABCMeta):
+    """
+    Analysis is a base class representing an analysis of a file, URL or endpoint.
+    It requires an API connection to Intezer.
+    """
     def __init__(self, api: IntezerApi = None):
+        """
+        :param api: The API connection to Intezer.
+        """
         self.status = None
         self.analysis_id = None
         self.analysis_time: Optional[datetime.datetime] = None
@@ -37,10 +44,10 @@ def wait_for_completion(self,
                             sleep_before_first_check=False,
                             timeout: Optional[datetime.timedelta] = None):
         """
-        Blocks until the analysis is completed
-        :param interval: The interval to wait between checks
-        :param sleep_before_first_check: Whether to sleep before the first status check
-        :param timeout: Maximum duration to wait for analysis completion
+        Blocks until the analysis is completed.
+        :param interval: The interval to wait between checks in seconds.
+        :param sleep_before_first_check: Whether to sleep before the first status check.
+        :param timeout: Maximum duration to wait for analysis completion in seconds.
         """
         start_time = datetime.datetime.utcnow()
         if not interval:
@@ -58,11 +65,19 @@ def wait_for_completion(self,
                 status_code = self.check_status()
 
     def _is_analysis_running(self) -> bool:
+        """
+        Check if the analysis is running.
+        :return: True if the analysis is running, False otherwise.
+        """
         return self.status in (consts.AnalysisStatusCode.CREATED,
                                consts.AnalysisStatusCode.IN_PROGRESS,
                                consts.AnalysisStatusCode.QUEUED)
 
     def check_status(self) -> consts.AnalysisStatusCode:
+        """
+        Check the status of the analysis.
+        :return: The status of the analysis.
+        """
         if not self._is_analysis_running():
             raise errors.IntezerError('Analysis is not running')
 

intezer_sdk/endpoint_analysis.py

@@ -7,12 +7,28 @@
 
 
 class EndpointAnalysis(Analysis):
+    """
+    EndpointAnalysis is a class for analyzing endpoints. It is a subclass of the Analysis class and requires an API connection to Intezer.
+    """
     def __init__(self, api: IntezerApi = None):
+        """
+        Initializes an EndpointAnalysis object.
+
+        :param api: The API connection to Intezer.
+        """
         super().__init__(api)
         self._sub_analyses: List[SubAnalysis] = []
 
     @classmethod
     def from_analysis_id(cls, analysis_id: str, api: IntezerApi = None):
+        """
+        Returns an EndpointAnalysis instance with the given analysis ID.
+        Returns None when analysis doesn't exist.
+
+        :param analysis_id: The ID of the analysis to retrieve.
+        :param api: The API connection to Intezer.
+        :return: An EndpointAnalysis instance with the given analysis ID.
+        """
         api = api or get_global_api()
         response = api.get_endpoint_analysis_response(analysis_id, True)
         return cls._create_analysis_from_response(response, api, analysis_id)