From f778d303ae23863d4807d74bd6fee92de33851bb Mon Sep 17 00:00:00 2001
From: Reza Rahemtola <reza.rahemtola@epitech.eu>
Date: Tue, 10 Dec 2024 17:29:22 +0900
Subject: [PATCH] feat(near-api/python): Install, account and utilities
 examples

---
 docs/4.tools/near-api.md | 109 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)

diff --git a/docs/4.tools/near-api.md b/docs/4.tools/near-api.md
index 7509a0e029..e6539ef0c2 100644
--- a/docs/4.tools/near-api.md
+++ b/docs/4.tools/near-api.md
@@ -50,6 +50,12 @@ These examples are references to code snippets, feel free to explore the full co
   cargo add near-api
   ```
   </TabItem>
+  <TabItem value="python" label="🐍 Python">
+
+  ```shell
+  pip install py-near
+  ```
+  </TabItem>
 </Tabs>
 
 <hr class="subsection" />
@@ -85,6 +91,19 @@ These examples are references to code snippets, feel free to explore the full co
     start="2" end="2" />
 
   </TabItem>
+  <TabItem value="python" label="🐍 Python">
+
+  You can use the NEAR API by importing the `py_near` package, either entirely
+  ```python
+  import py_near
+  ```
+
+  or only the parts you need, for example:
+  ```python
+  from py_near.account import Account
+  from py_near.providers import JsonProvider
+  ```
+  </TabItem>
 </Tabs>
 
 <hr class="subsection" />
@@ -264,6 +283,9 @@ These examples are references to code snippets, feel free to explore the full co
     </Tabs>
 
   </TabItem>
+  <TabItem value="python" label="🐍 Python">
+  TODO: not exactly the same in Python, it's more and account + RPC URL, or a JSON RPC provider
+  </TabItem>
 </Tabs>
 
 
@@ -281,6 +303,15 @@ These examples are references to code snippets, feel free to explore the full co
     start="12" end="34" />
 
   </TabItem>
+  <TabItem value="python" label="🐍 Python">
+    You can pass multiple RPC providers to `JsonRpcProvider`
+
+    ```python
+    from py_near.providers import JsonProvider
+
+    provider = JsonProvider(["https://test.rpc.fastnear.com", "https://rpc.testnet.pagoda.co"])
+    ```
+  </TabItem>
 </Tabs>
 
 ---
@@ -306,6 +337,22 @@ This will return an Account object for you to interact with.
     start="5" end="7" />
 
   </TabItem>
+  <TabItem value="python" label="🐍 Python">
+    You can instantiate any account with the following code:
+
+    ```python
+    from py_near.account import Account
+
+    account = Account(account_id="example-account.testnet", rpc_addr="https://rpc.testnet.pagoda.co")
+    await account.startup()
+    ```
+
+    If you want to use it to submit transactions later, you need to also pass the `private_key` param:
+
+    ```python
+    account = Account(account_id="example-account.testnet", private_key="ed25519:...", rpc_addr="https://rpc.testnet.pagoda.co")
+    ```
+  </TabItem>
 </Tabs>
 
 <hr class="subsection" />
@@ -329,6 +376,17 @@ Gets the available and staked balance of an account in yoctoNEAR.
     start="13" end="18" />
 
   </TabItem>
+  <TabItem value="python" label="🐍 Python">
+
+    ```python
+    from py_near.account import Account
+
+    account = Account(account_id="example-account.testnet", rpc_addr="https://rpc.testnet.pagoda.co")
+    await account.startup()
+
+    account_balance = account.get_balance()
+    ```
+  </TabItem>
 </Tabs>
 
 <hr class="subsection" />
@@ -352,6 +410,17 @@ Get basic account information, such as its code hash and storage usage.
     start="21" end="21" />
 
   </TabItem>
+  <TabItem value="python" label="🐍 Python">
+
+    ```python
+    from py_near.account import Account
+
+    account = Account(account_id="example-account.testnet", rpc_addr="https://rpc.testnet.pagoda.co")
+    await account.startup()
+
+    account_state = account.fetch_state()
+    ```
+  </TabItem>
 </Tabs>
 
 <hr class="subsection" />
@@ -448,6 +517,20 @@ Returns the authorized apps of an account. This is a list of contracts that the
     start="65" end="82" />
 
   </TabItem>
+  <TabItem value="python" label="🐍 Python">
+
+    Create a sub-account and fund it with your main account:
+
+    ```python
+    from py_near.account import Account
+    from py_near.dapps.core import NEAR
+
+    account = Account(account_id="example-account.testnet", private_key="ed25519:...", rpc_addr="https://rpc.testnet.pagoda.co")
+    await account.startup()
+
+    res = account.create_account(account_id="sub.example-account.testnet", public_key="...", initial_balance=1 * NEAR))
+    ```
+  </TabItem>
 </Tabs>
 
 <hr class="subsection" />
@@ -496,6 +579,18 @@ Transfer NEAR tokens between accounts.
     start="22" end="28" />
 
   </TabItem>
+  <TabItem value="python" label="🐍 Python">
+
+    ```python
+    from py_near.account import Account
+    from py_near.dapps.core import NEAR
+
+    account = Account(account_id="example-account.testnet", private_key="ed25519:...", rpc_addr="https://rpc.testnet.pagoda.co")
+    await account.startup()
+
+    await account.send_money("receiver-account.testnet", 1 * NEAR))
+    ```
+  </TabItem>
 </Tabs>
 
 <hr class="subsection" />
@@ -745,6 +840,15 @@ Convert an amount in NEAR to an amount in yoctoNEAR.
     start="7" end="7" />
 
   </TabItem>
+  <TabItem value="python" label="🐍 Python">
+
+   ```python
+   from py_near.dapps.core import NEAR
+
+   amount_in_yocto = 1 * NEAR
+   ```
+
+  </TabItem>
 </Tabs>
 
 <hr class="subsection" />
@@ -791,5 +895,10 @@ Convert an amount in NEAR to an amount in yoctoNEAR.
   - [Github](https://github.com/near/near-api-rs)
   - [Full Examples](https://github.com/PiVortex/near-api-examples/tree/main/rust)
 
+  </TabItem>
+  <TabItem value="python" label="🐍 Python">
+
+    - [Phone number transfer](https://py-near.readthedocs.io/en/latest/clients/phone.html)
+
   </TabItem>
 </Tabs>