Quickstart
In this page you will get a glimpse of SiyuanHelper.
You might need a bit understanding of async/await in python to get things work, but it won't be hard. This quickstart tutorial won't cover much related stuff. So don't worry, let's just start.
Initialize
Most of the time, you'll only use the following code to generate a Siyuan instance.
from siyuanhelper.api import Siyuan
import asyncio
async def main():
siyuan = Siyuan()
asyncio.run(main())
Get a Block
A frequent demand is to search for some specific blocks.
We can look for a Block by its id.
We can also find a list of blocks by SQL query:
Use a Block
We might want to get some information about a block.
await block.ensure()
# sometimes, blocks are lazily-loaded, use ensure() to guarantee its availability
# pull() can be used to ensure the block is up-to-date
# await block.pull()
print(block.id)
print(block.updated)
print(block.markdown)
print(await block.attrs.get("custom-attr"))
Modifying a block is also possible.
another_block = await block.insert(DataType.markdown, "Another **block** after me.")
await block.delete()
Note
There is a delay between the modification and data queried by Siyuan API.
That is to say, though your modification to a block is instantly done, you can't immediately get its information from Siyuan API due to some caching mechanism I guess.
Play with Attributes
One of Siyuan Note's most powerful features is the custom attributes.
You can easily read and write block attributes with the help of Siyuan Helper.
Searching for blocks with attribute conditions hasn't been supported so far, but on our todo-list.
Cleaning Up
It is recommended to close the connection when your script exits. Not mandatory though.