From 6377dc7936a4376de90f0e6f87670e5e630cf34c Mon Sep 17 00:00:00 2001 From: Katistix <33645731+Katistic@users.noreply.github.com> Date: Sun, 17 Mar 2024 20:03:19 +1100 Subject: [PATCH] Add usage examples (#19) * Login example source * Use of API sections source * Use of No-Auth Requests source * Create getting-started examples readme * Update Getting-Started code Add our User-Agent * Update examples link * Remove duplicate line --- README.md | 4 +- examples/README.md | 131 ++++++++++++++++++++++++ examples/examples-source/login.py | 41 ++++++++ examples/examples-source/noauth.py | 14 +++ examples/examples-source/use_the_api.py | 37 +++++++ 5 files changed, 226 insertions(+), 1 deletion(-) create mode 100644 examples/README.md create mode 100644 examples/examples-source/login.py create mode 100644 examples/examples-source/noauth.py create mode 100644 examples/examples-source/use_the_api.py diff --git a/README.md b/README.md index a94f7c9b..53749ce6 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,8 @@ configuration = vrchatapi.Configuration( # Enter a context with an instance of the API client with vrchatapi.ApiClient(configuration) as api_client: + # Set our User-Agent as per VRChat Usage Policy + api_client.user_agent = "MyProject/1.0 my@email.com" # Instantiate instances of API classes auth_api = authentication_api.AuthenticationApi(api_client) @@ -67,7 +69,7 @@ with vrchatapi.ApiClient(configuration) as api_client: print("Logged in as:", current_user.display_name) ``` -See [example.py](https://github.com/vrchatapi/vrchatapi-python/blob/main/example.py) for more example usage on getting started. +See [Examples](https://github.com/vrchatapi/vrchatapi-python/blob/main/examples/README.md) for more example usage on getting started. ## Contributing diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..fde31310 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,131 @@ +## Getting Started Examples + +### Logging In + +```Python +# Step 1. We begin with creating a Configuration, which contains the username and password for authentication. +import vrchatapi +from vrchatapi.api import authentication_api +from vrchatapi.exceptions import UnauthorizedException +from vrchatapi.models.two_factor_auth_code import TwoFactorAuthCode +from vrchatapi.models.two_factor_email_code import TwoFactorEmailCode + +configuration = vrchatapi.Configuration( + username = 'username', + password = 'password', +) + +# Step 2. VRChat consists of several API's (WorldsApi, UsersApi, FilesApi, NotificationsApi, FriendsApi, etc...) +# Here we enter a context of the API Client and instantiate the Authentication API which is required for logging in. + +# Enter a context with an instance of the API client +with vrchatapi.ApiClient(configuration) as api_client: + # Set our User-Agent as per VRChat Usage Policy + api_client.user_agent = "MyProject/1.0 my@email.com" + + # Instantiate instances of API classes + auth_api = authentication_api.AuthenticationApi(api_client) + + try: + # Step 3. Calling getCurrentUser on Authentication API logs you in if the user isn't already logged in. + current_user = auth_api.get_current_user() + except UnauthorizedException as e: + if e.status == 200: + if "Email 2 Factor Authentication" in e.reason: + # Step 3.5. Calling email verify2fa if the account has 2FA disabled + auth_api.verify2_fa_email_code(two_factor_email_code=TwoFactorEmailCode(input("Email 2FA Code: "))) + elif "2 Factor Authentication" in e.reason: + # Step 3.5. Calling verify2fa if the account has 2FA enabled + auth_api.verify2_fa(two_factor_auth_code=TwoFactorAuthCode(input("2FA Code: "))) + current_user = auth_api.get_current_user() + else: + print("Exception when calling API: %s\n", e) + except vrchatapi.ApiException as e: + print("Exception when calling API: %s\n", e) + + print("Logged in as:", current_user.display_name) +``` + +### Using The API + +Okay, cool, we can log in, but what now? + +The openapi generator splits each section of the API into it's own class. As such, we need to import each section of the API we want to use seperately. Expanding on our log-in example: + +```Python +import vrchatapi +from vrchatapi.api import authentication_api +from vrchatapi.exceptions import UnauthorizedException +from vrchatapi.models.two_factor_auth_code import TwoFactorAuthCode +from vrchatapi.models.two_factor_email_code import TwoFactorEmailCode + +# We import the class that corrisponds to the section of the API we want to use +from vrchatapi.api.worlds_api import WorldsApi + +configuration = vrchatapi.Configuration( + username = 'username', + password = 'password', +) + +with vrchatapi.ApiClient(configuration) as api_client: + api_client.user_agent = "MyProject/1.0 my@email.com" + auth_api = authentication_api.AuthenticationApi(api_client) + + try: + current_user = auth_api.get_current_user() + except UnauthorizedException as e: + if e.status == 200: + if "Email 2 Factor Authentication" in e.reason: + auth_api.verify2_fa_email_code(two_factor_email_code=TwoFactorEmailCode(input("Email 2FA Code: "))) + elif "2 Factor Authentication" in e.reason: + auth_api.verify2_fa(two_factor_auth_code=TwoFactorAuthCode(input("2FA Code: "))) + current_user = auth_api.get_current_user() + else: + print("Exception when calling API: %s\n", e) + except vrchatapi.ApiException as e: + print("Exception when calling API: %s\n", e) + + print("Logged in as:", current_user.display_name) + + # Now we are logged in, we can init and use the API class :) + worlds_api = WorldsApi(api_client) # All API section classes require an ApiClient object to be passed! + active_worlds = worlds_api.get_active_worlds() +``` + +Here is a list of [all sections of the API:](https://github.com/vrchatapi/vrchatapi-python/tree/main/vrchatapi/api) +- `authentication_api.AuthenticationApi` +- `avatars_api.AvatarsApi` +- `economy_api.EconomyApi` +- `favorites_api.FavoritesApi` +- `files_api.FilesApi` +- `friends_api.FriendsApi` +- `groups_api.GroupsApi` +- `instances_api.InstancesApi` +- `invite_api.InviteApi` +- `notifications_api.NotificationsApi` +- `permissions_api.PermissionsApi` +- `playermoderation_api.PlayermoderationApi` +- `system_api.SystemApi` +- `users_api.UsersApi` +- `worlds_api.WorldsApi` + +### No Auth Requests + +But some requests don't require Authentication, so how do we use them without logging in? + +```Python +import vrchatapi + +# We import the class that corrisponds to the section of the API we want to use +from vrchatapi.api.worlds_api import WorldsApi + +# We don't add a configuration file/set a username and password +with vrchatapi.ApiClient() as api_client: + api_client.user_agent = "MyProject/1.0 my@email.com" + + # We don't use the authentication API at all, since we don't need to + world_api = WorldsApi(api_client) + world = world_api.get_world("wrld_000000000-0000-0000-0000-000000000000") + + print(f"World `{world.name}` was made by `{world.author_name}` ({world.author_id})") +``` \ No newline at end of file diff --git a/examples/examples-source/login.py b/examples/examples-source/login.py new file mode 100644 index 00000000..535ef3db --- /dev/null +++ b/examples/examples-source/login.py @@ -0,0 +1,41 @@ +# Step 1. We begin with creating a Configuration, which contains the username and password for authentication. +import vrchatapi +from vrchatapi.api import authentication_api +from vrchatapi.exceptions import UnauthorizedException +from vrchatapi.models.two_factor_auth_code import TwoFactorAuthCode +from vrchatapi.models.two_factor_email_code import TwoFactorEmailCode + +configuration = vrchatapi.Configuration( + username = 'username', + password = 'password', +) + +# Step 2. VRChat consists of several API's (WorldsApi, UsersApi, FilesApi, NotificationsApi, FriendsApi, etc...) +# Here we enter a context of the API Client and instantiate the Authentication API which is required for logging in. + +# Enter a context with an instance of the API client +with vrchatapi.ApiClient(configuration) as api_client: + # Set our User-Agent as per VRChat Usage Policy + api_client.user_agent = "MyProject/1.0 my@email.com" + + # Instantiate instances of API classes + auth_api = authentication_api.AuthenticationApi(api_client) + + try: + # Step 3. Calling getCurrentUser on Authentication API logs you in if the user isn't already logged in. + current_user = auth_api.get_current_user() + except UnauthorizedException as e: + if e.status == 200: + if "Email 2 Factor Authentication" in e.reason: + # Step 3.5. Calling email verify2fa if the account has 2FA disabled + auth_api.verify2_fa_email_code(two_factor_email_code=TwoFactorEmailCode(input("Email 2FA Code: "))) + elif "2 Factor Authentication" in e.reason: + # Step 3.5. Calling verify2fa if the account has 2FA enabled + auth_api.verify2_fa(two_factor_auth_code=TwoFactorAuthCode(input("2FA Code: "))) + current_user = auth_api.get_current_user() + else: + print("Exception when calling API: %s\n", e) + except vrchatapi.ApiException as e: + print("Exception when calling API: %s\n", e) + + print("Logged in as:", current_user.display_name) \ No newline at end of file diff --git a/examples/examples-source/noauth.py b/examples/examples-source/noauth.py new file mode 100644 index 00000000..01abf9d6 --- /dev/null +++ b/examples/examples-source/noauth.py @@ -0,0 +1,14 @@ +import vrchatapi + +# We import the class that corrisponds to the section of the API we want to use +from vrchatapi.api.worlds_api import WorldsApi + +# We don't add a configuration file/set a username and password +with vrchatapi.ApiClient() as api_client: + api_client.user_agent = "MyProject/1.0 my@email.com" + + # We don't use the authentication API at all, since we don't need to + world_api = WorldsApi(api_client) + world = world_api.get_world("wrld_000000000-0000-0000-0000-000000000000") + + print(f"World `{world.name}` was made by `{world.author_name}` ({world.author_id})") \ No newline at end of file diff --git a/examples/examples-source/use_the_api.py b/examples/examples-source/use_the_api.py new file mode 100644 index 00000000..34410efb --- /dev/null +++ b/examples/examples-source/use_the_api.py @@ -0,0 +1,37 @@ +import vrchatapi +from vrchatapi.api import authentication_api +from vrchatapi.exceptions import UnauthorizedException +from vrchatapi.models.two_factor_auth_code import TwoFactorAuthCode +from vrchatapi.models.two_factor_email_code import TwoFactorEmailCode + +# We import the class that corrisponds to the section of the API we want to use +from vrchatapi.api.worlds_api import WorldsApi + +configuration = vrchatapi.Configuration( + username = 'username', + password = 'password', +) + +with vrchatapi.ApiClient(configuration) as api_client: + api_client.user_agent = "MyProject/1.0 my@email.com" + auth_api = authentication_api.AuthenticationApi(api_client) + + try: + current_user = auth_api.get_current_user() + except UnauthorizedException as e: + if e.status == 200: + if "Email 2 Factor Authentication" in e.reason: + auth_api.verify2_fa_email_code(two_factor_email_code=TwoFactorEmailCode(input("Email 2FA Code: "))) + elif "2 Factor Authentication" in e.reason: + auth_api.verify2_fa(two_factor_auth_code=TwoFactorAuthCode(input("2FA Code: "))) + current_user = auth_api.get_current_user() + else: + print("Exception when calling API: %s\n", e) + except vrchatapi.ApiException as e: + print("Exception when calling API: %s\n", e) + + print("Logged in as:", current_user.display_name) + + # Now we are logged in, we can init and use the API class :) + worlds_api = WorldsApi(api_client) # All API section classes require an ApiClient object to be passed! + active_worlds = worlds_api.get_active_worlds() \ No newline at end of file