From 8bad5dc48a0faa7028f5d0bbdcb3325a3377fbdc Mon Sep 17 00:00:00 2001 From: Paul Tikken Date: Thu, 18 Apr 2024 18:55:34 +0000 Subject: [PATCH] [CveXplore-278] doc restructure WIP #219 --- CveXplore/main.py | 116 +++++++++++++++++++++++++++++------- README.rst | 4 +- docs/_static/custom.css | 5 +- docs/conf.py | 6 +- docs/package/code_base.rst | 6 ++ docs/package/query_data.rst | 4 +- 6 files changed, 112 insertions(+), 29 deletions(-) diff --git a/CveXplore/main.py b/CveXplore/main.py index 2ba8f36d..2a033f12 100644 --- a/CveXplore/main.py +++ b/CveXplore/main.py @@ -60,6 +60,13 @@ def _version(): class CveXplore(object): + """ + The CveXplore class is the main entry point for CveXplore. All functionality is available from straight from this + class or via the different subclasses / attributes. + + Group: + Main + """ def __init__(self, **kwargs): """ Create a new instance of CveXplore @@ -329,6 +336,12 @@ def get_single_store_entries( << Cves:CVE-2017-14445 >>, << Cves:CVE-2016-2354 >>] + >>> from CveXplore import CveXplore + >>> cvx = CveXplore() + >>> result = cvx.get_single_store_entries(("cves", {"cvss": {"$eq": 8}}), limit=0) + >>> len(result) + 32 + Args: query: Tuple which contains the entry_type and the dict_filter in a tuple. Choices for entry_type: @@ -422,18 +435,28 @@ def get_multi_store_entries( Method to perform *multiple* queries on *a single* or *multiple* collections in the data source and return the results. - A list of tuples which contains the entry_type and the dict_filter. - Choices for entry_type: - - capec; - - cpe; - - cwe; - - via4; - - cves; + Examples: - dict_filter is a dictionary representing a filter according to pymongo documentation. + >>> from CveXplore import CveXplore + >>> cvx = CveXplore() + >>> result = cvx.get_multi_store_entries([("CWE", {"id": "78"}), ("cves", {"id": "CVE-2009-0018"})]) + >>> result + [<< Cwe:78 >>, << Cves:CVE-2009-0018 >>] - example: - get_multi_store_entries([("cwe", {"id": "78"}), ("cves", {"id": "CVE-2009-0018"})]) + Args: + queries: A list of tuples which contains the entry_type and the dict_filter. Choices for entry_type: + + - capec; + - cpe; + - cwe; + - via4; + - cves; + + dict_filter is a dictionary representing a filter according to pymongo documentation. + limit: Limit the number of results to return. + + Returns: + A list with CveXploreObject's or None """ results = map( @@ -456,7 +479,18 @@ def cves_for_cpe(self, cpe_string: str) -> List[CveXploreObject] | None: """ Method for retrieving Cves that match a single CPE string. By default, the search will be made matching the configuration fields of the cves documents. - CPE string could be formatted like: ``cpe:2.3:o:microsoft:windows_7:*:sp1:*:*:*:*:*:*`` + + Examples: + + >>> from CveXplore import CveXplore + >>> cvx = CveXplore() + >>> cves = cvx.cves_for_cpe("cpe:2.3:o:microsoft:windows_7:*:sp1:*:*:*:*:*:*") + + Args: + cpe_string: CPE string to search for. + + Returns: + A list with CveXploreObject's or None """ cpe_regex_string = create_cpe_regex_string(cpe_string) @@ -468,7 +502,16 @@ def cves_for_cpe(self, cpe_string: str) -> List[CveXploreObject] | None: return cves - def _validate_cve_id(self, cve_id: str): + def _validate_cve_id(self, cve_id: str) -> str: + """ + Method for validating a CVE ID. + + Args: + cve_id: The CVE ID to validate. + + Returns: + A validated CVE ID. + """ reg_match = re.compile(r"[cC][vV][eE]-\d{4}-\d{4,10}") if reg_match.match(cve_id) is not None: cve_id = cve_id.upper() @@ -487,7 +530,12 @@ def _validate_cve_id(self, cve_id: str): def cve_by_id(self, cve_id: str) -> CveXploreObject | None: """ Method to retrieve a single CVE from the database by its CVE ID number. - The number format should be either CVE-2000-0001, cve-2000-0001 or 2000-0001. + + Args: + cve_id: The number format should be either CVE-2000-0001, cve-2000-0001 or 2000-0001. + + Returns: + A CveXploreObject or None """ cve_id = self._validate_cve_id(cve_id=cve_id) @@ -495,8 +543,13 @@ def cve_by_id(self, cve_id: str) -> CveXploreObject | None: def cves_by_id(self, *cve_ids: str) -> Union[Iterable[CveXploreObject], Iterable]: """ - Method to retrieve a multiple CVE's from the database by its CVE ID number. - The number format should be either CVE-2000-0001, cve-2000-0001 or 2000-0001. + Method to retrieve multiple CVE's from the database by their CVE ID numbers. + + Args: + cve_ids: The number format should be either CVE-2000-0001, cve-2000-0001 or 2000-0001. + + Returns: + A list with CveXploreObject's or empty list """ ret_data = [] for cve_id in cve_ids: @@ -509,9 +562,14 @@ def cves_by_id(self, *cve_ids: str) -> Union[Iterable[CveXploreObject], Iterable def capec_by_cwe_id(self, cwe_id: int) -> List[CveXploreObject] | None: """ - Method to retrieve capecs related to a specific CWE ID - """ + Method to retrieve CAPEC's related to a specific CWE ID + Args: + cwe_id: The CWE ID to retrieve CAPEC for. + + Returns: + A list with CveXploreObject's or None + """ cwe = self.get_single_store_entry("cwe", {"id": cwe_id}) if cwe is not None: @@ -521,9 +579,14 @@ def capec_by_cwe_id(self, cwe_id: int) -> List[CveXploreObject] | None: def last_cves(self, limit: int = 10) -> List[CveXploreObject] | None: """ - Method to retrieve the last entered / changed cves. By default, limited to 10. - """ + Method to retrieve the last entered / changed cves. + + Args: + limit: The amount of results to return; defaults to 10. + Returns: + A list with CveXploreObject's or None + """ results = ( getattr(self.datasource, "store_cves") .find() @@ -540,10 +603,12 @@ def last_cves(self, limit: int = 10) -> List[CveXploreObject] | None: def get_db_content_stats(self) -> dict | str: """ - Properties returning the stats from the database. Stats consist of the time last modified and the document count + This method request the statistics from the database and consist of the time last modified and the document count per cvedb store in the database. - """ + Returns: + The stats from the database. + """ stats = defaultdict(dict) if not isinstance(self.datasource, ApiDatabaseSource): @@ -581,6 +646,11 @@ def get_db_content_stats(self) -> dict | str: return f"Using api endpoint: {self.datasource.baseurl}" - def __repr__(self): - """String representation of object""" + def __repr__(self) -> str: + """ + String representation of object + + Returns: + String representation of object + """ return f"<< CveXplore:{self.version} >>" diff --git a/README.rst b/README.rst index e556d150..c8dbd888 100644 --- a/README.rst +++ b/README.rst @@ -145,12 +145,12 @@ And to let CveXplore talk to an Cve Search API (only query POST endpoint needed) >>> cvx.version '0.1.2' -For More options please check the full documentation +For More options please check the package documentation Command line usage ------------------ -CveXplore has a 'Python Click' (`Documentation `_) command line interpreter +CveXplore has a 'Python Click' (`Documentation `_) command line interpreter available. Click provides an extensive help function to guide you through the different options; also check the full documentation for examples and usage instructions diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 43fb62dd..682efa77 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -20,8 +20,9 @@ a.reference.internal span.viewcode-link span.pre:hover, color: #b0eb00; } -em.sig-param a.n.reference.internal span.n span.pre { - color: #ff9575; +em.sig-param a.n.reference.internal span.n span.pre, +dt[id^='p-'] span.n.sig-name { + color: #4567f1 !important; font-weight: normal; } diff --git a/docs/conf.py b/docs/conf.py index 3a39cd3a..926a5913 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,7 +7,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = "CveXplore" -copyright = "2024, Paul Tikken" +copyright = "2020, Paul Tikken" author = "Paul Tikken" # -- General configuration --------------------------------------------------- @@ -48,6 +48,10 @@ (r".*\.__(str|repr)__", 5), ] +python_type_aliases = { + "CveXplore.api.helpers.cve_search_api.ApiBaseClass": "ApiBaseClass", +} + python_apigen_order_tiebreaker = "alphabetical" rst_prolog = """ diff --git a/docs/package/code_base.rst b/docs/package/code_base.rst index 812e318f..403b50d6 100644 --- a/docs/package/code_base.rst +++ b/docs/package/code_base.rst @@ -1,4 +1,10 @@ Code base --------- +Main +#### +.. python-apigen-group:: main + +Other +##### .. python-apigen-group:: classes diff --git a/docs/package/query_data.rst b/docs/package/query_data.rst index 669a9379..ec842b04 100644 --- a/docs/package/query_data.rst +++ b/docs/package/query_data.rst @@ -79,7 +79,9 @@ iterate over the requested results): ... << Capec:1 >> -**WARNING The collection specific find method does not adhere to the default limit of 10** + +.. warning:: + The collection specific find method does not adhere to the default limit of 10 If you would limit (or sort / skip) the returned results you could append additional commands to your original query: