Upgrading dependencies, rewriting README and running tests (#24)

* 🚧 Starting to revamp the library

* 💚 refs #24 Fixing tests

Author: vcampitelli

.github/workflows/test.yaml

@@ -3,9 +3,10 @@ name: run_tests
 
 # Controls when the action will run. 
 on:
-  #push:
-
-  # Allows you to run this workflow manually from the Actions tab
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
   workflow_dispatch:
 
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
@@ -21,18 +22,16 @@ jobs:
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
       # Setup the system with the repository code, Java, and Ruby
-      - uses: actions/checkout@v2
-      - uses: isbang/compose-action@v1.0.0
+      - uses: actions/checkout@v4
+      - uses: isbang/compose-action@v1.5.1
         with:
           compose-file: './src/test/docker/docker-compose.yml'
           down-flags: '--volumes'
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v5
         with:
-          python-version: '3.9.x'
+          python-version: '3.12.2'
       - name: Install fusionauth library
-        run: |
-          pip3 install .
-          pip3 install unittest2
+        run: pip3 install .
         shell: bash
       - name: Check to see if FusionAuth is loaded
         run: |

README.md

@@ -1,65 +1,189 @@
-## FusionAuth Python Client ![semver 2.0.0 compliant](http://img.shields.io/badge/semver-2.0.0-brightgreen.svg?style=flat-square)
-If you're integrating FusionAuth with a Python 3 application, this library will speed up your development time.
+# FusionAuth Python Client ![semver 2.0.0 compliant](http://img.shields.io/badge/semver-2.0.0-brightgreen.svg?style=flat-square)
+
+## Intro
+
+<!--
+tag::forDocSite[]
+-->
+
+If you're integrating FusionAuth with a Python 3 application, this library will speed up your development time. Please also make sure to check our [SDK Usage Suggestions page](https://fusionauth.io/docs/sdks/#usage-suggestions).
 
 For additional information and documentation on FusionAuth refer to [https://fusionauth.io](https://fusionauth.io).
 
-### Install
+## Install
 To install the FusionAuth Python Client package run:
 
 ```bash
 pip install fusionauth-client
 ```
 
-This library can be found on PyPI
-* https://pypi.org/project/fusionauth-client/
+This library can be found on PyPI at https://pypi.org/project/fusionauth-client/.
+
+## Examples
+
+### Set Up
+
+First, you have to make sure you have a running FusionAuth instance. If you don't have one already, the easiest way to install FusionAuth is [via Docker](https://fusionauth.io/docs/get-started/download-and-install/docker), but there are [other ways](https://fusionauth.io/docs/get-started/download-and-install). By default, it'll be running on `localhost:9011`.
+
+Then, you have to [create an API Key](https://fusionauth.io/docs/apis/authentication#managing-api-keys) in the admin UI to allow calling API endpoints.
 
-### Coding
-And then include the package in your code by using the following statement.
+You are now ready to use this library.
+
+### Create the Client
+
+Include the package in your code by using the following statement.
 
 ```python
 from fusionauth.fusionauth_client import FusionAuthClient
 ```
 
-Now you're ready to begin making requests to FusionAuth. You will need to supply an API key you created in FusionAuth, the folowing example assumes an API key of `6b87a398-39f2-4692-927b-13188a81a9a3`.
+Now you're ready to begin making requests to FusionAuth. You will need to supply an API key you created in FusionAuth, the following example assumes an API key of `6b87a398-39f2-4692-927b-13188a81a9a3`.
 
 ```python
 client = FusionAuthClient('6b87a398-39f2-4692-927b-13188a81a9a3', 'http://localhost:9011')
 ```
 
-Here's an example which logs a user in:
+### Error Handling
+
+After every request is made, you need to check for any errors and handle them. To avoid cluttering things up, we'll omit the error handling in the next examples, but you should do something like the following.
+
+
+### Create an Application
+
+To create an [Application](https://fusionauth.io/docs/get-started/core-concepts/applications), use the `create_application()` method.
 
 ```python
-from fusionauth.fusionauth_client import FusionAuthClient
-client = FusionAuthClient(API_KEY, 'http://localhost:9011')
+data = {
+    'application': {
+        'name': 'ChangeBank'
+    }
+}
+
+result = client.create_application(data)
+
+# Handle errors as shown in the beginning of the Examples section
+
+# Otherwise parse the successful response
+print(result.success_response)
+```
+
+[Check the API docs for this endpoint](https://fusionauth.io/docs/apis/applications#create-an-application)
 
+### Adding Roles to an Existing Application
+
+To add [roles to an Application](https://fusionauth.io/docs/get-started/core-concepts/applications#roles), use `create_application_role()`.  
+
+```python
 data = {
-    'loginId': loginId,
-    'password': password,
-    'applicationId': My_App_ID
+    'role': {
+        'name': 'customer',
+        'description': 'Default role for regular customers',
+        'isDefault': 1
+    }
 }
 
-print(client.login(data).success_response)
+result = client.create_application_role(
+    application_id='5a89377e-a250-4b15-b766-377ecc9b9fc9',
+    request=data
+)
+
+# Handle errors as shown in the beginning of the Examples section
+
+# Otherwise parse the successful response
+print(result.success_response)
+```
+
+[Check the API docs for this endpoint](https://fusionauth.io/docs/apis/applications#create-an-application-role)
+
+### Retrieve Application Details
+
+To fetch details about an [Application](https://fusionauth.io/docs/get-started/core-concepts/applications), use `retrieve_application()`. 
+
+```python
+result = client.retrieve_application(
+    application_id='5a89377e-a250-4b15-b766-377ecc9b9fc9'
+)
+print(result.success_response)
+```
+
+[Check the API docs for this endpoint](https://fusionauth.io/docs/apis/applications#retrieve-an-application)
+
+### Delete an Application
+
+To delete an [Application](https://fusionauth.io/docs/get-started/core-concepts/applications), use `delete_application()`.
+
+```python
+client.delete_application(
+    application_id='5a89377e-a250-4b15-b766-377ecc9b9fc9'
+)
+```
+
+[Check the API docs for this endpoint](https://fusionauth.io/docs/apis/applications#delete-an-application)
+
+### Lock a User
+
+To [prevent a User from logging in](https://fusionauth.io/docs/get-started/core-concepts/users), use `deactivate_user()`. 
+
+```python
+client.deactivate_user(
+    user_id='231b982c-9304-4642-9bac-492d6917f5aa'
+)
+```
+
+
+[Check the API docs for this endpoint](https://fusionauth.io/docs/apis/users#delete-a-user)
+
+### Registering a User
+
+To [register a User in an Application](https://fusionauth.io/docs/get-started/core-concepts/users#registrations), use `register()`.
+
+The code below also adds a `customer` role and a custom `appBackgroundColor` property to the User Registration.
+
+```python
+result = client.register(
+    user_id='231b982c-9304-4642-9bac-492d6917f5aa',
+    request={
+        'registration': {
+            'applicationId': '5a89377e-a250-4b15-b766-377ecc9b9fc9',
+            'roles': [
+                'customer'
+            ],
+            'data': {
+                'appBackgroundColor': '#096324'
+            }
+        }
+    }
+)
+print(result.success_response)
 ```
 
-Each method in the client library includes documentation to describe the use and parameters. In addition to this resource, review the API documentation. https://fusionauth.io/docs/v1/tech/apis/
+[Check the API docs for this endpoint](https://fusionauth.io/docs/apis/registrations#create-a-user-registration-for-an-existing-user)
+
+<!--
+end::forDocSite[]
+-->
+
 
-If you encounter a bug with this library, please open an issue.
 
 ## Questions and support
 
-If you have a question or support issue regarding this client library, we'd love to hear from you.
+If you find any bugs in this library, [please open an issue](https://github.com/FusionAuth/fusionauth-python-client/issues). Note that changes to the `FusionAuthClient` class have to be done on the [FusionAuth Client Builder repository](https://github.com/FusionAuth/fusionauth-client-builder/blob/master/src/main/client/python.client.ftl), which is responsible for generating that file.
+
+But if you have a question or support issue, we'd love to hear from you.
 
-If you have a paid edition with support included, please [open a ticket in your account portal](https://account.fusionauth.io/account/support/). Learn more about [paid editions here](https://fusionauth.io/pricing).
+If you have a paid plan with support included, please [open a ticket in your account portal](https://account.fusionauth.io/account/support/). Learn more about [paid plan here](https://fusionauth.io/pricing).
 
 Otherwise, please [post your question in the community forum](https://fusionauth.io/community/forum/).
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/FusionAuth/fusionauth-python-client.
 
+Note: if you want to change the `FusionAuthClient` class, you have to do it on the [FusionAuth Client Builder repository](https://github.com/FusionAuth/fusionauth-client-builder/blob/master/src/main/client/python.client.ftl), which is responsible for generating all client libraries we support.
+
 ## License
 
-This code is available as open source under the terms of the [Apache v2.0 License](https://opensource.org/licenses/Apache-2.0).
+This code is available as open source under the terms of the [Apache v2.0 License](https://opensource.org/license/apache-2-0).
 
 ## Upgrade Policy
 

build.savant

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018-2023, FusionAuth, All Rights Reserved
+ * Copyright (c) 2018-2024, FusionAuth, All Rights Reserved
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -80,7 +80,7 @@ target(name: "setup-python", description: "Gets the python dependencies") {
   proc1.consumeProcessOutput(System.out, System.err)
   proc1.waitFor()
 
-  def proc2 = "python3 -m pip install --user --upgrade wheel twine unittest2 requests deprecated".execute()
+  def proc2 = "python3 -m pip install --user --upgrade wheel twine requests deprecated".execute()
   proc2.consumeProcessOutput(System.out, System.err)
   proc2.waitFor()
 }

src/test/docker/docker-compose.yml

@@ -2,21 +2,27 @@ version: '3'
 
 services:
   db:
-    image: postgres:12.9
+    image: postgres:16.0-alpine
     environment:
       PGDATA: /var/lib/postgresql/data/pgdata
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
+    healthcheck:
+      test: [ "CMD-SHELL", "pg_isready -U postgres" ]
+      interval: 5s
+      timeout: 5s
+      retries: 5
     networks:
-      - db
+      - db_net
     restart: unless-stopped
     volumes:
       - db_data:/var/lib/postgresql/data
 
   fusionauth:
     image: fusionauth/fusionauth-app:latest
     depends_on:
-      - db
+      db:
+        condition: service_healthy
     environment:
       DATABASE_URL: jdbc:postgresql://db:5432/fusionauth
       DATABASE_ROOT_USERNAME: postgres
@@ -25,23 +31,28 @@ services:
       DATABASE_PASSWORD: fusionauth
       FUSIONAUTH_APP_MEMORY: 512M
       FUSIONAUTH_APP_RUNTIME_MODE: development
+      FUSIONAUTH_APP_SILENT_MODE: true
       FUSIONAUTH_APP_URL: http://fusionauth:9011
-      SEARCH_TYPE: database
       FUSIONAUTH_APP_KICKSTART_FILE: /usr/local/fusionauth/kickstart/kickstart.json
-
+      SEARCH_TYPE: database
     networks:
-     - db
+      - db_net
     restart: unless-stopped
     ports:
       - 9011:9011
     volumes:
-      - fa_config:/usr/local/fusionauth/config
+      - fusionauth_config:/usr/local/fusionauth/config
       - ./kickstart:/usr/local/fusionauth/kickstart
+    healthcheck:
+      test: curl --silent --fail http://localhost:9011/api/status -o /dev/null -w "%{http_code}"
+      interval: 5s
+      timeout: 5s
+      retries: 5
 
 networks:
-  db:
+  db_net:
     driver: bridge
 
 volumes:
   db_data:
-  fa_config:
+  fusionauth_config:

src/test/docker/poll-for-kickstart-finish.sh

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2022, FusionAuth, All Rights Reserved
+# Copyright (c) 2024, FusionAuth, All Rights Reserved
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,13 +13,26 @@
 # either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
 #
-imgid=`docker container ls|grep fusiona|awk '{print $1}'`
 
-cnt=`docker logs $imgid 2>&1|grep 'Starting FusionAuth HTTP server' |wc -l`
+cd $(dirname "$0")
 
-while [ $cnt != "1" ]; do
-  echo "waiting $cnt $imgid";
-  cnt=`docker logs $imgid 2>&1|grep 'Starting FusionAuth HTTP server' |wc -l`;
-  sleep 5;
+isFusionAuthReady () {
+  docker compose logs fusionauth 2>&1 | grep -Fq 'Completed [POST] request to [/api/user/registration/00000000-0000-0000-0000-000000000008]'
+}
+
+max_retries=20
+i=1
+while [ "$i" -le "$max_retries" ]; do
+  echo -n "[$i/$max_retries] Waiting for FusionAuth server to start... "
+
+  if isFusionAuthReady; then
+    echo "READY"
+    exit 0
+  fi
+
+  echo "NOT READY"
+  sleep 5
+  i=$((i + 1))
 done
 
+exit 1