update wikipage name and instructions

Author: danlu1

docs/tutorials/python/tutorial_scripts/wiki.py

@@ -37,46 +37,47 @@
 
 # Section1: Create, read, and update wiki pages
 # Create a new wiki page for the project with plain text markdown
-wiki_page_1 = WikiPage(
+root_wiki_page = WikiPage(
     owner_id=my_test_project.id,
     title="My Root Wiki Page",
     markdown="# Welcome to My Root Wiki\n\nThis is a sample root wiki page created with the Synapse client.",
 ).store()
 
-# OR you can create a wiki page with an existing markdown file
+# OR you can create a wiki page with an existing markdown file. More instructions can be found in section 2.
 markdown_file_path = "path/to/your_markdown_file.md"
-wiki_page_1 = WikiPage(
+root_wiki_page = WikiPage(
     owner_id=my_test_project.id,
     title="My First Root Wiki Page Version with existing markdown file",
     markdown=markdown_file_path,
 ).store()
 
 # Create a new wiki page with updated content
-wiki_page_2 = WikiPage(
+root_wiki_page_new = WikiPage(
     owner_id=my_test_project.id,
-    title="My First Root Wiki Page Version 1",
-    markdown="# Welcome to My Root Wiki Version 1\n\nThis is a sample root wiki page created with the Synapse client.",
-    id=wiki_page_1.id,
+    title="My First Root Wiki Page NEW",
+    markdown="# Welcome to My Root Wiki NEW\n\nThis is a sample root wiki page created with the Synapse client.",
+    id=root_wiki_page.id,
 ).store()
 
 # Restore the wiki page to the original version
 wiki_page_restored = WikiPage(
-    owner_id=my_test_project.id, id=wiki_page_1.id, wiki_version="0"
+    owner_id=my_test_project.id, id=root_wiki_page.id, wiki_version="0"
 ).restore()
 
 # check if the content is restored
 comparisons = [
-    wiki_page_1.markdown_file_handle_id == wiki_page_restored.markdown_file_handle_id,
-    wiki_page_1.id == wiki_page_restored.id,
-    wiki_page_1.title == wiki_page_restored.title,
+    root_wiki_page.markdown_file_handle_id
+    == wiki_page_restored.markdown_file_handle_id,
+    root_wiki_page.id == wiki_page_restored.id,
+    root_wiki_page.title == wiki_page_restored.title,
 ]
 print(f"All fields match: {all(comparisons)}")
 
 # Create a sub-wiki page
-sub_wiki = WikiPage(
+sub_wiki_1 = WikiPage(
     owner_id=my_test_project.id,
     title="Sub Wiki Page 1",
-    parent_id=wiki_page_1.id,  # Use the ID of the parent wiki page we created '633033'
+    parent_id=root_wiki_page.id,  # Use the ID of the parent wiki page we created '633033'
     markdown="# Sub Page 1\n\nThis is a sub-page of another wiki.",
 ).store()
 
@@ -85,18 +86,18 @@
 print(wiki_header_tree)
 
 # Once you know the wiki page id, you can retrieve the wiki page with the id
-retrieved_wiki = WikiPage(owner_id=my_test_project.id, id=sub_wiki.id).get()
+retrieved_wiki = WikiPage(owner_id=my_test_project.id, id=sub_wiki_1.id).get()
 print(f"Retrieved wiki page with title: {retrieved_wiki.title}")
 
 # Or you can retrieve the wiki page with the title
-retrieved_wiki = WikiPage(owner_id=my_test_project.id, title=wiki_page_1.title).get()
+retrieved_wiki = WikiPage(owner_id=my_test_project.id, title=sub_wiki_1.title).get()
 print(f"Retrieved wiki page with title: {retrieved_wiki.title}")
 
 # Check if the retrieved wiki page is the same as the original wiki page
 comparisons = [
-    wiki_page_1.markdown_file_handle_id == retrieved_wiki.markdown_file_handle_id,
-    wiki_page_1.id == retrieved_wiki.id,
-    wiki_page_1.title == retrieved_wiki.title,
+    sub_wiki_1.markdown_file_handle_id == retrieved_wiki.markdown_file_handle_id,
+    sub_wiki_1.id == retrieved_wiki.id,
+    sub_wiki_1.title == retrieved_wiki.title,
 ]
 print(f"All fields match: {all(comparisons)}")
 
@@ -120,9 +121,9 @@ def hello_world():
 """
 
 # Create wiki page from markdown text
-markdown_wiki_1 = WikiPage(
+sub_wiki_2 = WikiPage(
     owner_id=my_test_project.id,
-    parent_id=wiki_page_1.id,
+    parent_id=root_wiki_page.id,
     title="Sub Page 2 created from markdown text",
     markdown=markdown_content,
 ).store()
@@ -134,111 +135,150 @@ def hello_world():
     gz.write("This is a markdown file")
 
 # Create wiki page from markdown file
-markdown_wiki_2 = WikiPage(
+sub_wiki_3 = WikiPage(
     owner_id=my_test_project.id,
-    parent_id=wiki_page_1.id,
+    parent_id=root_wiki_page.id,
     title="Sub Page 3 created from markdown file",
     markdown=markdown_file_path,
 ).store()
 
 # Download the markdown file
-# delete the markdown file after downloading
+# delete the markdown file after uploading to test the download function
+os.remove(markdown_file_path)
+# Note: If the markdown is generated from plain text using the client, the downloaded file will be named wiki_markdown_<wiki_page_title>.md.gz. If it is generated from an existing markdown file, the downloaded file will retain the original filename with the .gz suffix appended.
+# Download the markdown file for sub_wiki_2 that is created from markdown text
+wiki_page_markdown_2 = WikiPage(
+    owner_id=my_test_project.id, id=sub_wiki_2.id
+).get_markdown(
+    download_file=True,
+    download_location=".",
+    download_file_name=f"wiki_markdown_{sub_wiki_2.title}.md.gz",
+)
+print(
+    f"Wiki page markdown for sub_wiki_2 successfully downloaded: {os.path.exists(f'wiki_markdown_{sub_wiki_2.title}.md.gz')}"
+)
+# clean up the downloaded markdown file
+os.remove(f"wiki_markdown_{sub_wiki_2.title}.md.gz")
+
+# Download the markdown file for sub_wiki_3 that is created from a markdown file
+wiki_page_markdown_3 = WikiPage(
+    owner_id=my_test_project.id, id=sub_wiki_3.id
+).get_markdown(
+    download_file=True, download_location=".", download_file_name=markdown_file_path
+)
+print(
+    f"Wiki page markdown for sub_wiki_3 successfully downloaded: {os.path.exists(markdown_file_path)}"
+)
+# clean up the downloaded markdown file
 os.remove(markdown_file_path)
-markdown_file_2 = WikiPage(
-    owner_id=my_test_project.id, id=markdown_wiki_2.id
-).get_markdown(download_file=True, download_location=".")
-
-print(f"Markdown file downloaded to: {markdown_file_2}")
 
 # Section 3: WikiPage with Attachments
 # Create a temporary file for the attachment
 attachment_file_name = "temp_attachment.txt.gz"
 with gzip.open(attachment_file_name, "wt", encoding="utf-8") as gz:
     gz.write("This is a sample attachment.")
 
-# reformat the attachment file name to be a valid attachment path
+# reformat '.' and '_' in the attachment file name to be a valid attachment path
 attachment_file_name_reformatted = attachment_file_name.replace(".", "%2E")
 attachment_file_name_reformatted = attachment_file_name_reformatted.replace("_", "%5F")
 
-wiki_with_attachments = WikiPage(
+sub_wiki_4 = WikiPage(
     owner_id=my_test_project.id,
-    parent_id=wiki_page_1.id,
+    parent_id=root_wiki_page.id,
     title="Sub Page 4 with Attachments",
     markdown=f"# Sub Page 4 with Attachments\n\nThis is a attachment: ${{previewattachment?fileName={attachment_file_name_reformatted}}}",
     attachments=[attachment_file_name],
 ).store()
 
 # Get attachment handles
 attachment_handles = WikiPage(
-    owner_id=my_test_project.id, id=wiki_with_attachments.id
+    owner_id=my_test_project.id, id=sub_wiki_4.id
 ).get_attachment_handles()
-print(f"Found {len(attachment_handles['list'])} attachments")
+print(f"Attachment handles: {attachment_handles['list']}")
+
+# Get attachment URL without downloading
+wiki_page_attachment_url = WikiPage(
+    owner_id=my_test_project.id, id=sub_wiki_4.id
+).get_attachment(
+    file_name="temp_attachment.txt.gz",
+    download_file=False,
+)
+print(f"Attachment URL: {wiki_page_attachment_url}")
 
-# Delete the attachment file after uploading --> check if the file is deleted
-os.remove(attachment_file_name)
 # Download an attachment
-wiki_page = WikiPage(
-    owner_id=my_test_project.id, id=wiki_with_attachments.id
+# Delete the attachment file after uploading to test the download function
+os.remove(attachment_file_name)
+wiki_page_attachment = WikiPage(
+    owner_id=my_test_project.id, id=sub_wiki_4.id
 ).get_attachment(
     file_name=attachment_file_name,
     download_file=True,
     download_location=".",
 )
 print(f"Attachment downloaded: {os.path.exists(attachment_file_name)}")
+os.remove(attachment_file_name)
 
-# Get attachment URL without downloading
-wiki_page_url = WikiPage(
-    owner_id=my_test_project.id, id=wiki_with_attachments.id
-).get_attachment(
+# Download an attachment preview. Instead of using the file_name from the attachmenthandle response when isPreview=True, you should use the original file name in the get_attachment_preview request. The downloaded file will still be named according to the file_name provided in the response when isPreview=True.
+# Get attachment preview URL without downloading
+attachment_preview_url = WikiPage(
+    owner_id=my_test_project.id, id=sub_wiki_4.id
+).get_attachment_preview(
     file_name="temp_attachment.txt.gz",
     download_file=False,
 )
-print(f"Attachment URL: {wiki_page_url}")
+print(f"Attachment preview URL: {attachment_preview_url}")
 
-# Download an attachment preview--? Failed to download the attachment preview, synapseclient.core.exceptions.SynapseHTTPError: 404 Client Error: Cannot find a wiki attachment for OwnerID: syn68493645, ObjectType: ENTITY, WikiPageId: 633100, fileName: preview.txt
-attachment_handles = WikiPage(
-    owner_id=my_test_project.id, id=wiki_with_attachments.id
-).get_attachment_handles()
-print(f"Attachment handles: {attachment_handles}")
-wiki_page = WikiPage(
-    owner_id=my_test_project.id, id=wiki_with_attachments.id
+# Download an attachment preview
+attachment_preview = WikiPage(
+    owner_id=my_test_project.id, id=sub_wiki_4.id
 ).get_attachment_preview(
-    file_name="preview.txt",
+    file_name="temp_attachment.txt.gz",
     download_file=True,
     download_location=".",
 )
+# From the attachment preview URL or attachment handle response, the downloaded preview file is preview.txt
+os.remove("preview.txt")
 
 # Section 4: WikiHeader - Working with Wiki Hierarchy
-
 # Get wiki header tree (hierarchy)
-# Note: Uncomment to actually get the header tree
 headers = WikiHeader.get(owner_id=my_test_project.id)
 print(f"Found {len(headers)} wiki pages in hierarchy")
+print(f"Wiki header tree: {headers}")
 
 # Section 5. WikiHistorySnapshot - Version History
-# Get wiki history
-history = WikiHistorySnapshot.get(owner_id=my_test_project.id, id=wiki_page_1.id)
-
-print(f"Found {len(history)} versions in history for {wiki_page_1.title}")
+# Get wiki history for root_wiki_page
+history = WikiHistorySnapshot.get(owner_id=my_test_project.id, id=root_wiki_page.id)
+print(f"History: {history}")
 
 # Section 6. WikiOrderHint - Ordering Wiki Pages
-# Get wiki order hint --> failed to get the order hint
+# Set the wiki order hint
 order_hint = WikiOrderHint(owner_id=my_test_project.id).get()
+print(f"Order hint for {my_test_project.id}: {order_hint.id_list}")
+# As you can see from the printed message, the order hint is not set by default, so you need to set it explicitly at the beginning.
+order_hint.id_list = [
+    root_wiki_page.id,
+    sub_wiki_3.id,
+    sub_wiki_4.id,
+    sub_wiki_1.id,
+    sub_wiki_2.id,
+]
+order_hint.store()
 print(f"Order hint for {my_test_project.id}: {order_hint}")
 
 # Update wiki order hint
-order_hint.id_list = [wiki_page_1.id]
-
-print(f"Created order hint for {len(order_hint.id_list)} wiki pages")
-
-# Update order hint
-order_hint.id_list = ["633084", "633085", "633086", "633087", "633088"]  # Reorder
+order_hint = WikiOrderHint(owner_id=my_test_project.id).get()
+order_hint.id_list = [
+    root_wiki_page.id,
+    sub_wiki_1.id,
+    sub_wiki_2.id,
+    sub_wiki_3.id,
+    sub_wiki_4.id,
+]
 order_hint.store()
+print(f"Order hint for {my_test_project.id}: {order_hint}")
 
 # Delete a wiki page
-wiki_page_to_delete = WikiPage(
-    owner_id=my_test_project.id, id=wiki_with_attachments.id
-).delete()
+wiki_page_to_delete = WikiPage(owner_id=my_test_project.id, id=sub_wiki_3.id).delete()
 
 # clean up
 my_test_project.delete()