add example and also add __str implementation for each return type

README.md

@@ -11,6 +11,7 @@ pip install metaphor-python
 ```
 
 ## Usage
+
 Import the package and initialize the Metaphor client with your API key:
 
 ```python
@@ -20,6 +21,7 @@ client = Metaphor(api_key="your-api-key")
 ```
 
 ## Search Request
+
 ```python
 
 response = client.search("funny article about tech culture",
@@ -42,6 +44,7 @@ for result in response.results:
 ```
 
 ## Retrieve Document Contents
+
 ```python
 ids = ["8U71IlQ5DUTdsZFherhhYA", "X3wd0PbJmAvhu_DQjDKA7A"]
 response = client.get_contents(ids)
@@ -50,25 +53,27 @@ for content in response.contents:
     print(content.title, content.url)
 ```
 
-## Reference 
+## Reference
 
 ### `Metaphor.search()`
+
 This function performs a search on the Metaphor API.
-#### Args:
-- query (str): The search query.
-- **options**: Additional search options. Valid options are:
-    - `num_results` (int): The number of search results to return.
-    - `include_domains` (list): A list of domains to include in the search.
-    - `exclude_domains` (list): A list of domains to exclude from the search.
-    - `start_crawl_date` (str): The start date for the crawl (in YYYY-MM-DD format).
-    - `end_crawl_date` (str): The end date for the crawl (in YYYY-MM-DD format).
-    - `start_published_date` (str): The start date for when the document was published (in YYYY-MM-DD format).
-    - `end_published_date` (str): The end date for when the document was published (in YYYY-MM-DD format).
-    - `use_autoprompt` (bool): Whether to use autoprompt for the search.
-    - `type` (str): The type of document to search for.
 
+#### Args
 
-#### Returns:
+- query (str): The search query.
+- **options**: Additional search options. Valid options are:
+  - `num_results` (int): The number of search results to return.
+  - `include_domains` (list): A list of domains to include in the search.
+  - `exclude_domains` (list): A list of domains to exclude from the search.
+  - `start_crawl_date` (str): The start date for the crawl (in YYYY-MM-DD format).
+  - `end_crawl_date` (str): The end date for the crawl (in YYYY-MM-DD format).
+  - `start_published_date` (str): The start date for when the document was published (in YYYY-MM-DD format).
+  - `end_published_date` (str): The end date for when the document was published (in YYYY-MM-DD format).
+  - `use_autoprompt` (bool): Whether to use autoprompt for the search.
+  - `type` (str): The type of document to search for.
+
+#### Returns
 `SearchResponse`: A dataclass containing the search results.
 
 ### `Metaphor.find_similar()`
@@ -83,7 +88,8 @@ This function performs a search on the Metaphor API.
     - `end_crawl_date` (str): The end date for the crawl (in YYYY-MM-DD format).
     - `start_published_date` (str): The start date for when the document was published (in YYYY-MM-DD format).
     - `end_published_date` (str): The end date for when the document was published (in YYYY-MM-DD format).
-#### Returns:
+
+#### Returns
 `SearchResponse`: A dataclass containing the search results.
 
 # Contribution

examples/basic_search.py

@@ -0,0 +1,12 @@
+from metaphor_python import Metaphor
+
+client = Metaphor("fa0fcc27-312c-4d5e-b06d-f101f9717e91")
+
+response = client.search("funny article about tech culture",
+    num_results=5,
+    use_autoprompt=True,
+    include_domains=["nytimes.com", "wsj.com"],
+    start_published_date="2023-06-12"
+)
+
+print(response)

metaphor_python/api.py

@@ -76,6 +76,14 @@ def __init__(self, title, url, id, score=None, published_date=None, author=None,
         self.id = id
         self.published_date = published_date
         self.author = author
+    def __str__(self):
+        return (f"Title: {self.title}\n"
+                f"URL: {self.url}\n"
+                f"ID: {self.id}\n"
+                f"Score: {self.score}\n"
+                f"Published Date: {self.published_date}\n"
+                f"Author: {self.author}\n"
+                f"Extract: {self.extract}")
 
 @dataclass
 class DocumentContent:
@@ -90,10 +98,19 @@ def __init__(self, id, url, title, extract, **kwargs):
         self.title = title
         self.extract = extract
 
+    def __str__(self):
+        return (f"ID: {self.id}\n"
+                f"URL: {self.url}\n"
+                f"Title: {self.title}\n"
+                f"Extract: {self.extract}")
+
 @dataclass
 class GetContentsResponse:
     contents: List[DocumentContent]
 
+    def __str__(self):
+        return "\n\n".join(str(content) for content in self.contents)
+
 @dataclass
 class SearchResponse:
     results: List[Result]
@@ -105,6 +122,9 @@ def get_contents(self):
         ids = [result.id for result in self.results]
         return self.api.get_contents(ids)
 
+    def __str__(self):
+        return "\n\n".join(str(result) for result in self.results)
+
 class Metaphor:
     def __init__(self, api_key: str):
         self.base_url = "https://api.metaphor.systems"